@react-md/core 1.0.0-next.11 → 1.0.0-next.13

package/src/useThrottledFunction.ts

@@ -4,7 +4,7 @@ import { type AnyFunction, type CancelableFunction } from "./types.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ThrottledFunction<F extends AnyFunction> = CancelableFunction<
   (...args: Parameters<F>) => ReturnType<F>
@@ -13,8 +13,7 @@ export type ThrottledFunction<F extends AnyFunction> = CancelableFunction<
 /**
  * Creates a function that will only be called once every X milliseconds.
  *
- * @example
- * Throttling Search API Requests
+ * @example Throttling Search API Requests
  * ```tsx
  * import { TextField, useThrottledFunction, useUnmounted } from "@react-md/core";
  * import { useState } from "react";
@@ -84,7 +83,7 @@ export type ThrottledFunction<F extends AnyFunction> = CancelableFunction<
  *
  * @see `useDebouncedFunction` for debounce behavior instead. (Call a
  * function only if it has not been called again for X milliseconds).
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useThrottledFunction<F extends AnyFunction>(
   func: F,

package/src/useToggle.ts

@@ -3,7 +3,7 @@ import { useCallback, useState } from "react";
 import type { UseStateInitializer, UseStateSetter } from "./types.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ToggleHookReturnValue {
   toggled: boolean;
@@ -15,8 +15,7 @@ export interface ToggleHookReturnValue {
 
 /**
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { Button, useToggle } from "@react-md/core";
  * import type { ReactElement } from "react";

package/src/useUnmounted.ts

@@ -3,8 +3,7 @@ import { useEffect, useRef } from "react";
 import type { NonNullRef } from "./types.js";
 
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { useUnmounted } from "@react-md/core";
  * import { useEffect, useState } from "react";
@@ -29,7 +28,7 @@ import type { NonNullRef } from "./types.js";
  *   return null;
  * }
  * ```
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useUnmounted(): NonNullRef<boolean> {
   const unmounted = useRef(false);

package/src/useWindowSize.ts

@@ -8,7 +8,7 @@ import {
 } from "./useResizeListener.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface WindowSizeOptions
   extends Omit<ResizeListenerOptions, "disabled" | "onUpdate"> {
@@ -48,8 +48,7 @@ export interface WindowSizeOptions
 /**
  * This is just a convenience wrapper around the {@link useResizeListener}.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { useWindowSize } from "@react-md/core";
  * import type { ReactElement } from "react";
@@ -67,7 +66,7 @@ export interface WindowSizeOptions
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useWindowSize(options: WindowSizeOptions = {}): ElementSize {
   const {

package/src/utils/RenderRecursively.tsx

@@ -2,14 +2,40 @@
 import { type ComponentType, type ReactElement, type ReactNode } from "react";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type RecursiveItem<T = Record<string, unknown>> = T & {
   items?: readonly RecursiveItem<T>[];
 };
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
+ */
+export interface RecursiveItemKeyOptions<Item = Record<string, unknown>> {
+  item: RecursiveItem<Item>;
+  depth: number;
+  index: number;
+}
+
+/**
+ * This is the default implementation for {@link RenderRecursivelyProps.getItemKey}.
+ *
+ * ```ts
+ * return `${options.depth}-${options.index}`
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function getRecursiveItemKey<Item = Record<string, unknown>>(
+  options: RecursiveItemKeyOptions<Item>
+): string {
+  const { depth, index } = options;
+
+  return `${depth}-${index}`;
+}
+
+/**
+ * @since 6.0.0
  */
 export interface RenderRecursiveItemsProps<
   Item = Record<string, unknown>,
@@ -36,7 +62,7 @@ export interface RenderRecursiveItemsProps<
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface RenderRecursivelyProps<
   Item = Record<string, unknown>,
@@ -65,12 +91,13 @@ export interface RenderRecursivelyProps<
    *
    * @example
    * ```ts
-   * getItemKey={(item) => item.id}
+   * getItemKey={({ item }) => item.id}
    * ```
    *
-   * @defaultValue `() => ${parents.length}-${index}`.
+   * @see {@link getRecursiveItemKey}
+   * @defaultValue `({ index, depth }) => ${depth}-${index}`.
    */
-  getItemKey?(item: RecursiveItem<Item>): string;
+  getItemKey?(options: RecursiveItemKeyOptions<Item>): string;
 }
 
 /**
@@ -161,12 +188,18 @@ export interface RenderRecursivelyProps<
  * ```
  *
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function RenderRecursively<Item, Data>(
   props: RenderRecursivelyProps<Item, Data>
 ): ReactElement {
-  const { data, items, render: Render, getItemKey, parents = [] } = props;
+  const {
+    data,
+    items,
+    render: Render,
+    getItemKey = getRecursiveItemKey,
+    parents = [],
+  } = props;
 
   return (
     <>
@@ -187,7 +220,7 @@ export function RenderRecursively<Item, Data>(
 
         return (
           <Render
-            key={getItemKey ? getItemKey(item) : `${depth}-${index}`}
+            key={getItemKey({ item, depth, index })}
             // typecast since it should be undefined in renderer as well?
             data={data}
             item={item}

package/src/utils/__tests__/RenderRecursively.tsx

@@ -71,7 +71,7 @@ function Test(): ReactElement {
       data={activeId}
       items={items}
       render={Render}
-      getItemKey={(item) => item.id}
+      getItemKey={({ item }) => item.id}
     />
   );
 }

package/src/utils/alphaNumericSort.ts

@@ -5,20 +5,19 @@ import { type TextExtractor } from "../types.js";
  * The default `Intl.Collator` that should be used for sorting large lists.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare#performance
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const DEFAULT_COLLATOR = new Intl.Collator("en-US", {
   numeric: true,
   caseFirst: "upper",
 });
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface AlphaNumericSortOptions<T> {
   /**
    * The extractor is only required when the list of items are not strings.
    *
-   * @example
-   * Simple Example
+   * @example Simple Example
    * ```ts
    * interface Item {
    *   name: string;
@@ -31,7 +30,6 @@ export interface AlphaNumericSortOptions<T> {
    * })`
    * ```
    *
-   * @remarks
    * For javascript developers, this will throw an error in dev mode if an
    * extractor is not provided for non-string lists.
    *
@@ -44,8 +42,7 @@ export interface AlphaNumericSortOptions<T> {
    * provided if the language for your app is not `"en-US"` or you'd like to
    * provide some custom sorting options.
    *
-   * @example
-   * Custom Compare using Intl.Collator
+   * @example Custom Compare using Intl.Collator
    * ```ts
    * const collator = new Intl.Collator("en-US", {
    *   numeric: false,
@@ -73,8 +70,7 @@ export interface AlphaNumericSortOptions<T> {
 }
 
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```ts
  * const items = ["World", "Hello"];
  *
@@ -90,8 +86,7 @@ export function alphaNumericSort<T extends string>(
   options?: Omit<AlphaNumericSortOptions<T>, "extractor">
 ): readonly T[];
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```ts
  * interface Item {
  *   name: string;

package/src/utils/applyRef.ts

@@ -4,8 +4,7 @@ import type { MutableRefObject, Ref } from "react";
  * A small utility function that allows me to apply a passed in ref along with
  * my own custom ref logic.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { HTMLAttributes, forwardRef } from "react";
  * import { applyRef } from "@react-md/core";

package/src/utils/bem.ts

@@ -25,10 +25,9 @@ export type BEMResult = (
 /**
  * Applies the BEM styled class name to an element.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```jsx
- * import { Bem } from "@react-md/core":
+ * import { bem } from "@react-md/core":
  *
  * const styles = bem("my-component"):
  *

package/src/utils/getClientPosition.ts

@@ -1,6 +1,6 @@
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ClientPositionMouseEvent {
   clientX: number;
@@ -9,7 +9,7 @@ export interface ClientPositionMouseEvent {
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ClientPositionTouchEvent {
   changedTouches: {
@@ -23,7 +23,7 @@ export type ClientPositionEvent =
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ClientPositionOptions {
   event: ClientPositionEvent;
@@ -32,7 +32,7 @@ export interface ClientPositionOptions {
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const getClientPosition = (options: ClientPositionOptions): number => {
   const { event, vertical } = options;

package/src/utils/getMiddleOfRange.ts

@@ -2,7 +2,7 @@ import { getRangeSteps } from "./getRangeSteps.js";
 import { nearest } from "./nearest.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface GetMiddleOfRangeOptions {
   min: number;
@@ -12,7 +12,7 @@ export interface GetMiddleOfRangeOptions {
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function getMiddleOfRange(options: GetMiddleOfRangeOptions): number {
   const { min, max, step } = options;

package/src/utils/getPercentage.ts

@@ -1,4 +1,4 @@
-/** @remarks \@since 4.0.1 */
+/** @since 4.0.1 */
 export interface GetPercentageOptions {
   /**
    * The min value allowed.
@@ -30,9 +30,8 @@ export interface GetPercentageOptions {
  * @returns the percentage that the `value` is between the `min` and `max`
  * values.
  *
- * @remarks
- * \@since 4.0.1 uses an object for options instead of multiple arguments.
- * \@since 6.0.0 Updated to be included in the public API and `validate`
+ * @since 4.0.1 uses an object for options instead of multiple arguments.
+ * @since 6.0.0 Updated to be included in the public API and `validate`
  * defaults to `false` instead of `true`.
  */
 export function getPercentage(options: GetPercentageOptions): number {

package/src/utils/getRangeDefaultValue.ts

@@ -6,7 +6,7 @@ import {
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface RangeDefaultValueOptions extends GetMiddleOfRangeOptions {
   defaultValue?: UseStateInitializer<number>;
@@ -14,7 +14,7 @@ export interface RangeDefaultValueOptions extends GetMiddleOfRangeOptions {
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function getRangeDefaultValue(
   options: RangeDefaultValueOptions

package/src/utils/getRangeSteps.ts

@@ -1,6 +1,6 @@
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface RangeStepsOptions {
   min: number;
@@ -12,9 +12,8 @@ export interface RangeStepsOptions {
  * Gets the number of steps in the allowed range of values.
  *
  * @internal
- * @remarks
- * \@since 2.5.0
- * \@since 6.0.0 Converted to using an object instead of multiple arguments and
+ * @since 2.5.0
+ * @since 6.0.0 Converted to using an object instead of multiple arguments and
  * renamed from `getSteps` to `getRangeSteps`.
  */
 export function getRangeSteps(options: RangeStepsOptions): number {

package/src/utils/identity.ts

@@ -1,5 +1,5 @@
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const identity = <T>(thing: T): T => thing;

package/src/utils/isElementVisible.ts

@@ -1,7 +1,7 @@
 /**
  * Note: requires the `$disable-display-none-class` variable to remain `false`.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const DISPLAY_NONE_CLASS = "rmd-display-none";
 
@@ -10,8 +10,7 @@ export const DISPLAY_NONE_CLASS = "rmd-display-none";
  * checking the element and all parents to see if they contain the
  * {@link DISPLAY_NONE_CLASS}.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * const treeItem = screen.getByRole("treeitem", { name: "Tree Item" });
  * const subTreeItem = screen.getByRole("treeitem", { Name: "Sub Tree Item" });
@@ -23,7 +22,7 @@ export const DISPLAY_NONE_CLASS = "rmd-display-none";
  * expect(isElementVisible(treeItem)).toBe(true);
  * expect(isElementVisible(subTreeItem)).toBe(true);
  * ```
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function isElementVisible(element: HTMLElement | null): boolean {
   if (!element) {

package/src/utils/loop.ts

@@ -1,5 +1,5 @@
 /**
- * @remarks \@since 2.7.0
+ * @since 2.7.0
  * @internal
  */
 export interface LoopOptions {
@@ -41,7 +41,7 @@ export interface LoopOptions {
  *
  * @internal
  * @param options - {@link LoopOptions}
- * @remarks \@since 2.7.0 The `min` option was added and the arguments changed to an
+ * @since 2.7.0 The `min` option was added and the arguments changed to an
  * object
  */
 export function loop(options: LoopOptions): number {

package/src/utils/nearest.ts

@@ -1,6 +1,6 @@
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface NearestOptions {
   min: number;
@@ -17,9 +17,8 @@ export interface NearestOptions {
  *
  * @see https://stackoverflow.com/a/13635455
  * @returns the value rounded to the nearest step in the min/max range
- * @remarks
- * \@since 2.5.0 Added the `range` param
- * \@since 6.0.0 Converted to using an object instead of multiple arguments.
+ * @since 2.5.0 Added the `range` param
+ * @since 6.0.0 Converted to using an object instead of multiple arguments.
  */
 export function nearest(options: NearestOptions): number {
   const { min, max, steps, value, range = max - min } = options;

package/src/utils/parseCssLengthUnit.ts

@@ -22,8 +22,7 @@ export interface ParseCssLengthUnitOptions {
  * - `rem`
  * - `em` (if {@link ParseCssLengthUnitOptions.container} is provided)
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```ts
  * parseCssLengthUnit({ value: "24px" }) // 24
  * parseCssLengthUnit({ value: "3.5rem" }) // 56
@@ -35,8 +34,7 @@ export interface ParseCssLengthUnitOptions {
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths}
  * @internal
- * @remarks
- * \@since 6.0.0 This was renamed from `unitToNumber`
+ * @since 6.0.0 This was renamed from `unitToNumber`
  */
 export function parseCssLengthUnit(options: ParseCssLengthUnitOptions): number {
   const { value, container, fallbackFontSize = 16 } = options;

package/src/utils/randomInt.ts

@@ -1,4 +1,4 @@
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface RandomIntOptions {
   /** @defaultValue `0` */
   min?: number;
@@ -12,7 +12,7 @@ export interface RandomIntOptions {
  *
  * @param options - the {@link RandomIntOptions}
  * @returns a random number
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function randomInt(options: RandomIntOptions = {}): number {
   const { min = 0, max = 10 } = options;

package/src/utils/wait.ts

@@ -1,6 +1,5 @@
 /**
- * @example
- * Wait some duration
+ * @example Wait some duration
  * ```ts
  * import { wait } from "@react-md/core";
  *
@@ -12,7 +11,7 @@
  * This util was just added to support random waits for mocking data and random
  * throttling.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const wait = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(() => resolve(), ms));

package/src/utils/withinRange.ts

@@ -1,6 +1,6 @@
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface WithinRangeOptions {
   min: number | undefined;
@@ -13,9 +13,8 @@ export interface WithinRangeOptions {
  * max values.
  *
  * @returns the updated value
- * @remarks
- * \@since 2.5.0
- * \@since 6.0.0 Converted to using an object instead of multiple arguments.
+ * @since 2.5.0
+ * @since 6.0.0 Converted to using an object instead of multiple arguments.
  */
 export function withinRange(options: WithinRangeOptions): number {
   const { min, max, value } = options;

package/src/window-splitter/WindowSplitter.tsx

@@ -9,7 +9,7 @@ import { type useWindowSplitter } from "./useWindowSplitter.js";
 const styles = bem("rmd-window-splitter");
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface WindowSplitterClassNameOptions {
   className?: string;
@@ -20,7 +20,7 @@ export interface WindowSplitterClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function windowSplitter(
   options: WindowSplitterClassNameOptions = {}
@@ -47,7 +47,7 @@ export function windowSplitter(
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/}
  */
 export interface BaseWindowSplitterProps
@@ -77,7 +77,7 @@ export interface BaseWindowSplitterProps
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type WindowSplitterProps = LabelRequiredForA11y<BaseWindowSplitterProps>;
 
@@ -86,7 +86,7 @@ export type WindowSplitterProps = LabelRequiredForA11y<BaseWindowSplitterProps>;
  * Most likely a client component since it relies on `useWindowSplitter`
  *
  * @see {@link useWindowSplitter} for an example usage
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const WindowSplitter = forwardRef<
   HTMLButtonElement,

package/src/window-splitter/useWindowSplitter.ts

@@ -23,7 +23,7 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface BaseWindowSplitterOptions<
   E extends HTMLElement = HTMLButtonElement,
@@ -43,13 +43,13 @@ export interface BaseWindowSplitterOptions<
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type WindowSplitterOptions<E extends HTMLElement = HTMLButtonElement> =
   BaseWindowSplitterOptions<E> & DraggableStateOptions;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface WindowSplitterWidgetProps<E extends HTMLElement>
   extends Required<DraggableMouseEventHandlers<E>>,
@@ -66,7 +66,7 @@ export interface WindowSplitterWidgetProps<E extends HTMLElement>
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface WindowSplitterImplementation<
   E extends HTMLElement = HTMLButtonElement,
@@ -77,8 +77,7 @@ export interface WindowSplitterImplementation<
 /**
  * Used to control the state for the `WindowSplitter` component.
  *
- * @example
- * Custom Implementation
+ * @example Custom Implementation
  * ```tsx
  * import { useWindowSplitter, WindowSplitterImplementation } from "@react-md/core";
  * import { useState } from "react";
@@ -105,7 +104,7 @@ export interface WindowSplitterImplementation<
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useWindowSplitter<E extends HTMLElement = HTMLButtonElement>(
   options: WindowSplitterOptions<E>

package/tsconfig.types.json

@@ -7,6 +7,6 @@
     "declarationDir": "./dist",
     "emitDeclarationOnly": true
   },
-  "include": ["src/**.ts", "src/**.tsx", "src/test-utils"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["node_modules", "**/__tests__/**"]
 }

package/tsdoc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"],
+  "supportForTags": {
+    "@since": true
+  },
+  "tagDefinitions": [
+    {
+      "tagName": "@since",
+      "syntaxKind": "block",
+      "allowMultiple": true
+    }
+  ]
+}

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @react-md/core@1.0.0-next.10 typecheck /home/mlaursen/code/react-md/packages/core
-> tsc --noEmit
-