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

package/dist/useWindowSize.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/useWindowSize.ts"],"sourcesContent":["\"use client\";\nimport { useState } from \"react\";\nimport { useResizeListener } from \"./useResizeListener.js\";\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface WindowSize {\n  height: number;\n  width: number;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface WindowSizeOptions extends AddEventListenerOptions {\n  /**\n   * @defaultValue `true`\n   */\n  throttle?: boolean;\n\n  /**\n   * Set this to `true` to ignore resize events that only updated the height.\n   * The hook can be disabled by setting this and {@link disableWidth} to\n   * `true`.\n   *\n   * @defaultValue `false`\n   */\n  disableHeight?: boolean;\n\n  /**\n   * Set this to `true` to ignore resize events that only updated the width.\n   * The hook can be disabled by setting this and {@link disableHeight} to\n   * `true`.\n   *\n   * @defaultValue `false`\n   */\n  disableWidth?: boolean;\n}\n\n/**\n * This is just a convenience wrapper around the {@link useResizeListener}.\n *\n * @example\n * Simple Example\n * ```tsx\n * import { useWindowSize } from \"@react-md/core\";\n * import type { ReactElement } from \"react\";\n * import { useState } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { height, width } = useWindowSize();\n *\n *   return (\n *     <>\n *       The current window size:\n *       <pre><code>{JSON.stringify(size, null, 2)}</code></pre>\n *     </>\n *   );\n * }\n * ```\n *\n * @remarks \\@since 6.0.0\n */\nexport function useWindowSize(options: WindowSizeOptions = {}): WindowSize {\n  const {\n    once,\n    signal,\n    capture,\n    passive,\n    throttle,\n    disableWidth,\n    disableHeight,\n  } = options;\n\n  const [size, setSize] = useState(() => {\n    if (typeof window === \"undefined\") {\n      return {\n        height: 0,\n        width: 0,\n      };\n    }\n\n    return {\n      height: window.innerHeight,\n      width: window.innerWidth,\n    };\n  });\n\n  useResizeListener({\n    once,\n    signal,\n    capture,\n    passive,\n    throttle,\n    disabled: disableHeight && disableWidth,\n    onUpdate() {\n      setSize((prevSize) => {\n        const nextSize: WindowSize = {\n          height: window.innerHeight,\n          width: window.innerWidth,\n        };\n\n        const isHeightChange =\n          !disableHeight && prevSize.height !== nextSize.height;\n        const isWidthChange =\n          !disableWidth && prevSize.width !== nextSize.width;\n\n        return isHeightChange || isWidthChange ? nextSize : prevSize;\n      });\n    },\n  });\n\n  return size;\n}\n"],"names":["useState","useResizeListener","useWindowSize","options","once","signal","capture","passive","throttle","disableWidth","disableHeight","size","setSize","window","height","width","innerHeight","innerWidth","disabled","onUpdate","prevSize","nextSize","isHeightChange","isWidthChange"],"mappings":"AAAA;AACA,SAASA,QAAQ,QAAQ,QAAQ;AACjC,SAASC,iBAAiB,QAAQ,yBAAyB;AAsC3D;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASC,cAAcC,UAA6B,CAAC,CAAC;IAC3D,MAAM,EACJC,IAAI,EACJC,MAAM,EACNC,OAAO,EACPC,OAAO,EACPC,QAAQ,EACRC,YAAY,EACZC,aAAa,EACd,GAAGP;IAEJ,MAAM,CAACQ,MAAMC,QAAQ,GAAGZ,SAAS;QAC/B,IAAI,OAAOa,WAAW,aAAa;YACjC,OAAO;gBACLC,QAAQ;gBACRC,OAAO;YACT;QACF;QAEA,OAAO;YACLD,QAAQD,OAAOG,WAAW;YAC1BD,OAAOF,OAAOI,UAAU;QAC1B;IACF;IAEAhB,kBAAkB;QAChBG;QACAC;QACAC;QACAC;QACAC;QACAU,UAAUR,iBAAiBD;QAC3BU;YACEP,QAAQ,CAACQ;gBACP,MAAMC,WAAuB;oBAC3BP,QAAQD,OAAOG,WAAW;oBAC1BD,OAAOF,OAAOI,UAAU;gBAC1B;gBAEA,MAAMK,iBACJ,CAACZ,iBAAiBU,SAASN,MAAM,KAAKO,SAASP,MAAM;gBACvD,MAAMS,gBACJ,CAACd,gBAAgBW,SAASL,KAAK,KAAKM,SAASN,KAAK;gBAEpD,OAAOO,kBAAkBC,gBAAgBF,WAAWD;YACtD;QACF;IACF;IAEA,OAAOT;AACT"}
+{"version":3,"sources":["../src/useWindowSize.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useState } from \"react\";\n\nimport { useSsr } from \"./SsrProvider.js\";\nimport { type ElementSize } from \"./types.js\";\nimport {\n  type ResizeListenerOptions,\n  useResizeListener,\n} from \"./useResizeListener.js\";\n\n/**\n * @since 6.0.0\n */\nexport interface WindowSizeOptions\n  extends Omit<ResizeListenerOptions, \"disabled\" | \"onUpdate\"> {\n  /**\n   * The default value to use in SSR environments for the window's height.\n   *\n   * @defaultValue `0`\n   */\n  ssrHeight?: number;\n\n  /**\n   * The default value to use in SSR environments for the window's width.\n   *\n   * @defaultValue `0`\n   */\n  ssrWidth?: number;\n\n  /**\n   * Set this to `true` to ignore resize events that only updated the height.\n   * The hook can be disabled by setting this and {@link disableWidth} to\n   * `true`.\n   *\n   * @defaultValue `false`\n   */\n  disableHeight?: boolean;\n\n  /**\n   * Set this to `true` to ignore resize events that only updated the width.\n   * The hook can be disabled by setting this and {@link disableHeight} to\n   * `true`.\n   *\n   * @defaultValue `false`\n   */\n  disableWidth?: boolean;\n}\n\n/**\n * This is just a convenience wrapper around the {@link useResizeListener}.\n *\n * @example Simple Example\n * ```tsx\n * import { useWindowSize } from \"@react-md/core/useWindowSize\";\n * import type { ReactElement } from \"react\";\n * import { useState } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { height, width } = useWindowSize();\n *\n *   return (\n *     <>\n *       The current window size:\n *       <pre><code>{JSON.stringify(size, null, 2)}</code></pre>\n *     </>\n *   );\n * }\n * ```\n *\n * @since 6.0.0\n */\nexport function useWindowSize(options: WindowSizeOptions = {}): ElementSize {\n  const {\n    once,\n    signal,\n    capture,\n    passive,\n    throttle,\n    ssrHeight = 0,\n    ssrWidth = 0,\n    disableWidth,\n    disableHeight,\n  } = options;\n\n  const ssr = useSsr();\n  const [size, setSize] = useState(() => {\n    if (typeof window === \"undefined\" || ssr) {\n      return {\n        height: ssrHeight,\n        width: ssrWidth,\n      };\n    }\n\n    return {\n      height: window.innerHeight,\n      width: window.innerWidth,\n    };\n  });\n\n  useResizeListener({\n    once,\n    signal,\n    capture,\n    passive,\n    throttle,\n    disabled: disableHeight && disableWidth,\n    onUpdate: useCallback(() => {\n      setSize((prevSize) => {\n        const nextSize: ElementSize = {\n          height: window.innerHeight,\n          width: window.innerWidth,\n        };\n\n        const isHeightChange =\n          !disableHeight && prevSize.height !== nextSize.height;\n        const isWidthChange =\n          !disableWidth && prevSize.width !== nextSize.width;\n\n        return isHeightChange || isWidthChange ? nextSize : prevSize;\n      });\n    }, [disableHeight, disableWidth]),\n  });\n\n  return size;\n}\n"],"names":["useCallback","useState","useSsr","useResizeListener","useWindowSize","options","once","signal","capture","passive","throttle","ssrHeight","ssrWidth","disableWidth","disableHeight","ssr","size","setSize","window","height","width","innerHeight","innerWidth","disabled","onUpdate","prevSize","nextSize","isHeightChange","isWidthChange"],"mappings":"AAAA;AAEA,SAASA,WAAW,EAAEC,QAAQ,QAAQ,QAAQ;AAE9C,SAASC,MAAM,QAAQ,mBAAmB;AAE1C,SAEEC,iBAAiB,QACZ,yBAAyB;AAwChC;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASC,cAAcC,UAA6B,CAAC,CAAC;IAC3D,MAAM,EACJC,IAAI,EACJC,MAAM,EACNC,OAAO,EACPC,OAAO,EACPC,QAAQ,EACRC,YAAY,CAAC,EACbC,WAAW,CAAC,EACZC,YAAY,EACZC,aAAa,EACd,GAAGT;IAEJ,MAAMU,MAAMb;IACZ,MAAM,CAACc,MAAMC,QAAQ,GAAGhB,SAAS;QAC/B,IAAI,OAAOiB,WAAW,eAAeH,KAAK;YACxC,OAAO;gBACLI,QAAQR;gBACRS,OAAOR;YACT;QACF;QAEA,OAAO;YACLO,QAAQD,OAAOG,WAAW;YAC1BD,OAAOF,OAAOI,UAAU;QAC1B;IACF;IAEAnB,kBAAkB;QAChBG;QACAC;QACAC;QACAC;QACAC;QACAa,UAAUT,iBAAiBD;QAC3BW,UAAUxB,YAAY;YACpBiB,QAAQ,CAACQ;gBACP,MAAMC,WAAwB;oBAC5BP,QAAQD,OAAOG,WAAW;oBAC1BD,OAAOF,OAAOI,UAAU;gBAC1B;gBAEA,MAAMK,iBACJ,CAACb,iBAAiBW,SAASN,MAAM,KAAKO,SAASP,MAAM;gBACvD,MAAMS,gBACJ,CAACf,gBAAgBY,SAASL,KAAK,KAAKM,SAASN,KAAK;gBAEpD,OAAOO,kBAAkBC,gBAAgBF,WAAWD;YACtD;QACF,GAAG;YAACX;YAAeD;SAAa;IAClC;IAEA,OAAOG;AACT"}

package/dist/utils/RenderRecursively.d.ts

@@ -1,12 +1,30 @@
 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 declare function getRecursiveItemKey<Item = Record<string, unknown>>(options: RecursiveItemKeyOptions<Item>): string;
+/**
+ * @since 6.0.0
  */
 export interface RenderRecursiveItemsProps<Item = Record<string, unknown>, Data = unknown> {
     data?: Data;
@@ -26,7 +44,7 @@ export interface RenderRecursiveItemsProps<Item = Record<string, unknown>, Data
     children?: ReactNode;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface RenderRecursivelyProps<Item = Record<string, unknown>, Data = unknown> {
     data?: Data;
@@ -49,12 +67,13 @@ export interface RenderRecursivelyProps<Item = Record<string, unknown>, Data = u
      *
      * @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;
 }
 /**
  * Helper component for recursively rendering specific data structures (mostly
@@ -63,17 +82,46 @@ export interface RenderRecursivelyProps<Item = Record<string, unknown>, Data = u
  *
  * @example
  * ```tsx
+ * "use client";
+ *
+ * import { Box } from "@react-md/core/box/Box";
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Divider } from "@react-md/core/divider/Divider";
+ * import { List } from "@react-md/core/list/List";
+ * import { useCollapseTransition } from "@react-md/core/transition/useCollapseTransition";
  * import {
- *   buildTree,
- *   List,
- *   ListItem,
- *   ListItemLink,
- *   RenderRecursively,
- *   TreeData,
  *   type DefaultTreeItemNode,
+ *   type TreeData,
+ * } from "@react-md/core/tree/types";
+ * import { type UseStateSetter } from "@react-md/core/types";
+ * import { useToggle } from "@react-md/core/useToggle";
+ * import {
  *   type RenderRecursiveItemsProps,
- * } from "@react-md/core";
- * import { type ReactElement } from "react";
+ *   RenderRecursively,
+ * } from "@react-md/core/utils/RenderRecursively";
+ * import { type ReactElement, useState } from "react";
+ *
+ * interface Data {
+ *   activeId: string;
+ *   setActiveId: UseStateSetter<string>;
+ * }
+ *
+ * export default function SimpleExample(): ReactElement {
+ *   const [activeId, setActiveId] = useState("/");
+ *   return (
+ *     <Box fullWidth disableWrap>
+ *       <Box stacked align="stretch">
+ *         <RenderRecursively
+ *           // this is optional and can be any sort of info
+ *           data={{ activeId, setActiveId }}
+ *           items={Object.values(navItems)}
+ *           render={Render}
+ *         />
+ *       </Box>
+ *       <div>Active route: {activeId}</div>
+ *     </Box>
+ *   );
+ * }
  *
  * const navItems = {
  *   "/": {
@@ -99,51 +147,78 @@ export interface RenderRecursivelyProps<Item = Record<string, unknown>, Data = u
  *   },
  *   "/divider-1": {
  *     itemId: "/divider-1",
- *     parentId: null
+ *     parentId: null,
  *   },
  *   "/route-2": {
- *     itemId: "/route-2"
+ *     itemId: "/route-2",
  *     parentId: null,
  *     children: "Route 2",
  *   },
  * } satisfies TreeData;
  *
- * function NestedNavigation(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {
- *   const { item, parents, children } = props;
- *   const { toggle, toggled: collapsed } = useToggle(false);
- *   const { elementProps } = useCollapseTransition({
- *     transitionIn: !collapsed,
- *   });
- *
- *   return (
- *     <li>
- *       <Button onClick={toggle}>{item.children}</Button>
- *       <List {...elementProps}>{children}</List>
- *     </li>
- *   ):
- * }
- *
- *
- * function Render(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {
- *   const { item, parents } = props;
+ * function Render(
+ *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>
+ * ): ReactElement {
+ *   const {
+ *     item,
+ *     parents,
+ *     // this is passed down from the root `RenderRecursively`
+ *     data,
+ *     // this _might_ be defined based on the implementation. it's set to any
+ *     // renderable element
+ *     children: _children,
+ *   } = props;
  *   if (item.itemId.includes("divider")) {
  *     return <Divider />;
  *   }
  *
  *   if (item.items) {
- *     return <NestedNavigation {...props} />
+ *     return <NestedNavigation {...props} />;
  *   }
  *
  *   const prefix = parents.map((parent) => parent.itemId).join("/");
+ *   const currentId = `${prefix}${item.itemId}`;
+ *   // I haven't figured out how to manage the type safety of this yet
+ *   const active = data?.activeId === currentId;
+ *   // this would normally be a link, but to keep the demo simple, it's a button
  *   return (
- *     <Link href={`${prefix}${item.itemId}`}>
+ *     <Button
+ *       theme={active ? "primary" : "clear"}
+ *       themeType={active ? "contained" : "flat"}
+ *       onClick={() => {
+ *         data?.setActiveId(currentId);
+ *       }}
+ *       style={{ justifyContent: "flex-start" }}
+ *     >
  *       {item.children}
- *     </Link>
+ *     </Button>
  *   );
  * }
- * ```
  *
+ * function NestedNavigation(
+ *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>
+ * ): ReactElement {
+ *   const {
+ *     item,
+ *     parents: _parents,
+ *     // this is passed down from the root `RenderRecursively`
+ *     data: _data,
+ *     children,
+ *   } = props;
+ *   const { toggle, toggled: collapsed } = useToggle(false);
+ *   const { elementProps } = useCollapseTransition({
+ *     transitionIn: !collapsed,
+ *   });
+ *
+ *   return (
+ *     <li>
+ *       <Button onClick={toggle}>{item.children}</Button>
+ *       <List {...elementProps}>{children}</List>
+ *     </li>
+ *   );
+ * }
+ * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export declare function RenderRecursively<Item, Data>(props: RenderRecursivelyProps<Item, Data>): ReactElement;

package/dist/utils/RenderRecursively.js

@@ -1,5 +1,17 @@
 // TODO: Figure out how to strictly enforce the data
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * This is the default implementation for {@link RenderRecursivelyProps.getItemKey}.
+ *
+ * ```ts
+ * return `${options.depth}-${options.index}`
+ * ```
+ *
+ * @since 6.0.0
+ */ export function getRecursiveItemKey(options) {
+    const { depth, index } = options;
+    return `${depth}-${index}`;
+}
 /**
  * Helper component for recursively rendering specific data structures (mostly
  * trees). The main use-case is for rendering site navigation and the `Tree`
@@ -7,17 +19,46 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  *
  * @example
  * ```tsx
+ * "use client";
+ *
+ * import { Box } from "@react-md/core/box/Box";
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Divider } from "@react-md/core/divider/Divider";
+ * import { List } from "@react-md/core/list/List";
+ * import { useCollapseTransition } from "@react-md/core/transition/useCollapseTransition";
  * import {
- *   buildTree,
- *   List,
- *   ListItem,
- *   ListItemLink,
- *   RenderRecursively,
- *   TreeData,
  *   type DefaultTreeItemNode,
+ *   type TreeData,
+ * } from "@react-md/core/tree/types";
+ * import { type UseStateSetter } from "@react-md/core/types";
+ * import { useToggle } from "@react-md/core/useToggle";
+ * import {
  *   type RenderRecursiveItemsProps,
- * } from "@react-md/core";
- * import { type ReactElement } from "react";
+ *   RenderRecursively,
+ * } from "@react-md/core/utils/RenderRecursively";
+ * import { type ReactElement, useState } from "react";
+ *
+ * interface Data {
+ *   activeId: string;
+ *   setActiveId: UseStateSetter<string>;
+ * }
+ *
+ * export default function SimpleExample(): ReactElement {
+ *   const [activeId, setActiveId] = useState("/");
+ *   return (
+ *     <Box fullWidth disableWrap>
+ *       <Box stacked align="stretch">
+ *         <RenderRecursively
+ *           // this is optional and can be any sort of info
+ *           data={{ activeId, setActiveId }}
+ *           items={Object.values(navItems)}
+ *           render={Render}
+ *         />
+ *       </Box>
+ *       <div>Active route: {activeId}</div>
+ *     </Box>
+ *   );
+ * }
  *
  * const navItems = {
  *   "/": {
@@ -43,54 +84,81 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  *   },
  *   "/divider-1": {
  *     itemId: "/divider-1",
- *     parentId: null
+ *     parentId: null,
  *   },
  *   "/route-2": {
- *     itemId: "/route-2"
+ *     itemId: "/route-2",
  *     parentId: null,
  *     children: "Route 2",
  *   },
  * } satisfies TreeData;
  *
- * function NestedNavigation(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {
- *   const { item, parents, children } = props;
- *   const { toggle, toggled: collapsed } = useToggle(false);
- *   const { elementProps } = useCollapseTransition({
- *     transitionIn: !collapsed,
- *   });
- *
- *   return (
- *     <li>
- *       <Button onClick={toggle}>{item.children}</Button>
- *       <List {...elementProps}>{children}</List>
- *     </li>
- *   ):
- * }
- *
- *
- * function Render(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {
- *   const { item, parents } = props;
+ * function Render(
+ *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>
+ * ): ReactElement {
+ *   const {
+ *     item,
+ *     parents,
+ *     // this is passed down from the root `RenderRecursively`
+ *     data,
+ *     // this _might_ be defined based on the implementation. it's set to any
+ *     // renderable element
+ *     children: _children,
+ *   } = props;
  *   if (item.itemId.includes("divider")) {
  *     return <Divider />;
  *   }
  *
  *   if (item.items) {
- *     return <NestedNavigation {...props} />
+ *     return <NestedNavigation {...props} />;
  *   }
  *
  *   const prefix = parents.map((parent) => parent.itemId).join("/");
+ *   const currentId = `${prefix}${item.itemId}`;
+ *   // I haven't figured out how to manage the type safety of this yet
+ *   const active = data?.activeId === currentId;
+ *   // this would normally be a link, but to keep the demo simple, it's a button
  *   return (
- *     <Link href={`${prefix}${item.itemId}`}>
+ *     <Button
+ *       theme={active ? "primary" : "clear"}
+ *       themeType={active ? "contained" : "flat"}
+ *       onClick={() => {
+ *         data?.setActiveId(currentId);
+ *       }}
+ *       style={{ justifyContent: "flex-start" }}
+ *     >
  *       {item.children}
- *     </Link>
+ *     </Button>
  *   );
  * }
- * ```
  *
+ * function NestedNavigation(
+ *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>
+ * ): ReactElement {
+ *   const {
+ *     item,
+ *     parents: _parents,
+ *     // this is passed down from the root `RenderRecursively`
+ *     data: _data,
+ *     children,
+ *   } = props;
+ *   const { toggle, toggled: collapsed } = useToggle(false);
+ *   const { elementProps } = useCollapseTransition({
+ *     transitionIn: !collapsed,
+ *   });
+ *
+ *   return (
+ *     <li>
+ *       <Button onClick={toggle}>{item.children}</Button>
+ *       <List {...elementProps}>{children}</List>
+ *     </li>
+ *   );
+ * }
+ * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */ export function RenderRecursively(props) {
-    const { data, items, render: Render, getItemKey, parents = [] } = props;
+    const { data, items, render: Render, getItemKey = getRecursiveItemKey, parents = [] } = props;
     return /*#__PURE__*/ _jsx(_Fragment, {
         children: items.map((item, index)=>{
             let children;
@@ -113,7 +181,11 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
                 item: item,
                 parents: parents,
                 children: children
-            }, getItemKey ? getItemKey(item) : `${depth}-${index}`);
+            }, getItemKey({
+                item,
+                depth,
+                index
+            }));
         })
     });
 }

package/dist/utils/RenderRecursively.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/RenderRecursively.tsx"],"sourcesContent":["// TODO: Figure out how to strictly enforce the data\nimport { type ComponentType, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport type RecursiveItem<T = Record<string, unknown>> = T & {\n  items?: readonly RecursiveItem<T>[];\n};\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface RenderRecursiveItemsProps<\n  Item = Record<string, unknown>,\n  Data = unknown,\n> {\n  data?: Data;\n\n  /**\n   * The current item to render.\n   */\n  item: RecursiveItem<Item>;\n\n  /**\n   * The list of parent items which can be used to determine the depth or \"share\n   * props\" if the items contained props.\n   */\n  parents: readonly RecursiveItem<Item>[];\n\n  /**\n   * This will be provided if the {@link item} had child items and will be the\n   * rendered content.\n   */\n  children?: ReactNode;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface RenderRecursivelyProps<\n  Item = Record<string, unknown>,\n  Data = unknown,\n> {\n  data?: Data;\n  items: readonly RecursiveItem<Item>[];\n\n  /**\n   * The renderer for each item.\n   */\n  render: ComponentType<RenderRecursiveItemsProps<Item, Data>>;\n\n  /**\n   * This should not be used for external users. This is used to build the\n   * {@link RenderRecursiveItemsProps.parents} list.\n   *\n   * @internal\n   * @defaultValue `[]`\n   */\n  parents?: readonly RecursiveItem<Item>[];\n\n  /**\n   * Gets a React `key` for a specific item. This should be provided if the\n   * items can be moved around to improve performance.\n   *\n   * @example\n   * ```ts\n   * getItemKey={(item) => item.id}\n   * ```\n   *\n   * @defaultValue `() => ${parents.length}-${index}`.\n   */\n  getItemKey?(item: RecursiveItem<Item>): string;\n}\n\n/**\n * Helper component for recursively rendering specific data structures (mostly\n * trees). The main use-case is for rendering site navigation and the `Tree`\n * component.\n *\n * @example\n * ```tsx\n * import {\n *   buildTree,\n *   List,\n *   ListItem,\n *   ListItemLink,\n *   RenderRecursively,\n *   TreeData,\n *   type DefaultTreeItemNode,\n *   type RenderRecursiveItemsProps,\n * } from \"@react-md/core\";\n * import { type ReactElement } from \"react\";\n *\n * const navItems = {\n *   \"/\": {\n *     href: \"/\",\n *     itemId: \"/\",\n *     parentId: null,\n *     children: \"Home\",\n *   },\n *   \"/route-1\": {\n *     itemId: \"/route-1\",\n *     parentId: null,\n *     children: \"Collapsible\",\n *   },\n *   \"/nested-route-1\": {\n *     itemId: \"/nested-route-1\",\n *     parentId: \"/route-1\",\n *     children: \"Child 1\",\n *   },\n *   \"/nested-route-2\": {\n *     itemId: \"/nested-route-2\",\n *     parentId: \"/route-2\",\n *     children: \"Child 2\",\n *   },\n *   \"/divider-1\": {\n *     itemId: \"/divider-1\",\n *     parentId: null\n *   },\n *   \"/route-2\": {\n *     itemId: \"/route-2\"\n *     parentId: null,\n *     children: \"Route 2\",\n *   },\n * } satisfies TreeData;\n *\n * function NestedNavigation(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {\n *   const { item, parents, children } = props;\n *   const { toggle, toggled: collapsed } = useToggle(false);\n *   const { elementProps } = useCollapseTransition({\n *     transitionIn: !collapsed,\n *   });\n *\n *   return (\n *     <li>\n *       <Button onClick={toggle}>{item.children}</Button>\n *       <List {...elementProps}>{children}</List>\n *     </li>\n *   ):\n * }\n *\n *\n * function Render(props: RenderRecursiveItemsProps<DefaultTreeItemNode>): ReactElement {\n *   const { item, parents } = props;\n *   if (item.itemId.includes(\"divider\")) {\n *     return <Divider />;\n *   }\n *\n *   if (item.items) {\n *     return <NestedNavigation {...props} />\n *   }\n *\n *   const prefix = parents.map((parent) => parent.itemId).join(\"/\");\n *   return (\n *     <Link href={`${prefix}${item.itemId}`}>\n *       {item.children}\n *     </Link>\n *   );\n * }\n * ```\n *\n *\n * @remarks \\@since 6.0.0\n */\nexport function RenderRecursively<Item, Data>(\n  props: RenderRecursivelyProps<Item, Data>\n): ReactElement {\n  const { data, items, render: Render, getItemKey, parents = [] } = props;\n\n  return (\n    <>\n      {items.map((item, index) => {\n        let children: ReactNode;\n        const depth = parents.length;\n        if (item.items?.length) {\n          children = (\n            <RenderRecursively\n              data={data}\n              items={item.items}\n              render={Render}\n              getItemKey={getItemKey}\n              parents={[...parents, item]}\n            />\n          );\n        }\n\n        return (\n          <Render\n            key={getItemKey ? getItemKey(item) : `${depth}-${index}`}\n            // typecast since it should be undefined in renderer as well?\n            data={data}\n            item={item}\n            parents={parents}\n          >\n            {children}\n          </Render>\n        );\n      })}\n    </>\n  );\n}\n"],"names":["RenderRecursively","props","data","items","render","Render","getItemKey","parents","map","item","index","children","depth","length"],"mappings":"AAAA,oDAAoD;;AA2EpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFC,GACD,OAAO,SAASA,kBACdC,KAAyC;IAEzC,MAAM,EAAEC,IAAI,EAAEC,KAAK,EAAEC,QAAQC,MAAM,EAAEC,UAAU,EAAEC,UAAU,EAAE,EAAE,GAAGN;IAElE,qBACE;kBACGE,MAAMK,GAAG,CAAC,CAACC,MAAMC;YAChB,IAAIC;YACJ,MAAMC,QAAQL,QAAQM,MAAM;YAC5B,IAAIJ,KAAKN,KAAK,EAAEU,QAAQ;gBACtBF,yBACE,KAACX;oBACCE,MAAMA;oBACNC,OAAOM,KAAKN,KAAK;oBACjBC,QAAQC;oBACRC,YAAYA;oBACZC,SAAS;2BAAIA;wBAASE;qBAAK;;YAGjC;YAEA,qBACE,KAACJ;gBAEC,6DAA6D;gBAC7DH,MAAMA;gBACNO,MAAMA;gBACNF,SAASA;0BAERI;eANIL,aAAaA,WAAWG,QAAQ,CAAC,EAAEG,MAAM,CAAC,EAAEF,MAAM,CAAC;QAS9D;;AAGN"}
+{"version":3,"sources":["../../src/utils/RenderRecursively.tsx"],"sourcesContent":["// TODO: Figure out how to strictly enforce the data\nimport { type ComponentType, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * @since 6.0.0\n */\nexport type RecursiveItem<T = Record<string, unknown>> = T & {\n  items?: readonly RecursiveItem<T>[];\n};\n\n/**\n * @since 6.0.0\n */\nexport interface RecursiveItemKeyOptions<Item = Record<string, unknown>> {\n  item: RecursiveItem<Item>;\n  depth: number;\n  index: number;\n}\n\n/**\n * This is the default implementation for {@link RenderRecursivelyProps.getItemKey}.\n *\n * ```ts\n * return `${options.depth}-${options.index}`\n * ```\n *\n * @since 6.0.0\n */\nexport function getRecursiveItemKey<Item = Record<string, unknown>>(\n  options: RecursiveItemKeyOptions<Item>\n): string {\n  const { depth, index } = options;\n\n  return `${depth}-${index}`;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface RenderRecursiveItemsProps<\n  Item = Record<string, unknown>,\n  Data = unknown,\n> {\n  data?: Data;\n\n  /**\n   * The current item to render.\n   */\n  item: RecursiveItem<Item>;\n\n  /**\n   * The list of parent items which can be used to determine the depth or \"share\n   * props\" if the items contained props.\n   */\n  parents: readonly RecursiveItem<Item>[];\n\n  /**\n   * This will be provided if the {@link item} had child items and will be the\n   * rendered content.\n   */\n  children?: ReactNode;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface RenderRecursivelyProps<\n  Item = Record<string, unknown>,\n  Data = unknown,\n> {\n  data?: Data;\n  items: readonly RecursiveItem<Item>[];\n\n  /**\n   * The renderer for each item.\n   */\n  render: ComponentType<RenderRecursiveItemsProps<Item, Data>>;\n\n  /**\n   * This should not be used for external users. This is used to build the\n   * {@link RenderRecursiveItemsProps.parents} list.\n   *\n   * @internal\n   * @defaultValue `[]`\n   */\n  parents?: readonly RecursiveItem<Item>[];\n\n  /**\n   * Gets a React `key` for a specific item. This should be provided if the\n   * items can be moved around to improve performance.\n   *\n   * @example\n   * ```ts\n   * getItemKey={({ item }) => item.id}\n   * ```\n   *\n   * @see {@link getRecursiveItemKey}\n   * @defaultValue `` ({ index, depth }) => `${depth}-${index}` ``\n   */\n  getItemKey?: (options: RecursiveItemKeyOptions<Item>) => string;\n}\n\n/**\n * Helper component for recursively rendering specific data structures (mostly\n * trees). The main use-case is for rendering site navigation and the `Tree`\n * component.\n *\n * @example\n * ```tsx\n * \"use client\";\n *\n * import { Box } from \"@react-md/core/box/Box\";\n * import { Button } from \"@react-md/core/button/Button\";\n * import { Divider } from \"@react-md/core/divider/Divider\";\n * import { List } from \"@react-md/core/list/List\";\n * import { useCollapseTransition } from \"@react-md/core/transition/useCollapseTransition\";\n * import {\n *   type DefaultTreeItemNode,\n *   type TreeData,\n * } from \"@react-md/core/tree/types\";\n * import { type UseStateSetter } from \"@react-md/core/types\";\n * import { useToggle } from \"@react-md/core/useToggle\";\n * import {\n *   type RenderRecursiveItemsProps,\n *   RenderRecursively,\n * } from \"@react-md/core/utils/RenderRecursively\";\n * import { type ReactElement, useState } from \"react\";\n *\n * interface Data {\n *   activeId: string;\n *   setActiveId: UseStateSetter<string>;\n * }\n *\n * export default function SimpleExample(): ReactElement {\n *   const [activeId, setActiveId] = useState(\"/\");\n *   return (\n *     <Box fullWidth disableWrap>\n *       <Box stacked align=\"stretch\">\n *         <RenderRecursively\n *           // this is optional and can be any sort of info\n *           data={{ activeId, setActiveId }}\n *           items={Object.values(navItems)}\n *           render={Render}\n *         />\n *       </Box>\n *       <div>Active route: {activeId}</div>\n *     </Box>\n *   );\n * }\n *\n * const navItems = {\n *   \"/\": {\n *     href: \"/\",\n *     itemId: \"/\",\n *     parentId: null,\n *     children: \"Home\",\n *   },\n *   \"/route-1\": {\n *     itemId: \"/route-1\",\n *     parentId: null,\n *     children: \"Collapsible\",\n *   },\n *   \"/nested-route-1\": {\n *     itemId: \"/nested-route-1\",\n *     parentId: \"/route-1\",\n *     children: \"Child 1\",\n *   },\n *   \"/nested-route-2\": {\n *     itemId: \"/nested-route-2\",\n *     parentId: \"/route-2\",\n *     children: \"Child 2\",\n *   },\n *   \"/divider-1\": {\n *     itemId: \"/divider-1\",\n *     parentId: null,\n *   },\n *   \"/route-2\": {\n *     itemId: \"/route-2\",\n *     parentId: null,\n *     children: \"Route 2\",\n *   },\n * } satisfies TreeData;\n *\n * function Render(\n *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>\n * ): ReactElement {\n *   const {\n *     item,\n *     parents,\n *     // this is passed down from the root `RenderRecursively`\n *     data,\n *     // this _might_ be defined based on the implementation. it's set to any\n *     // renderable element\n *     children: _children,\n *   } = props;\n *   if (item.itemId.includes(\"divider\")) {\n *     return <Divider />;\n *   }\n *\n *   if (item.items) {\n *     return <NestedNavigation {...props} />;\n *   }\n *\n *   const prefix = parents.map((parent) => parent.itemId).join(\"/\");\n *   const currentId = `${prefix}${item.itemId}`;\n *   // I haven't figured out how to manage the type safety of this yet\n *   const active = data?.activeId === currentId;\n *   // this would normally be a link, but to keep the demo simple, it's a button\n *   return (\n *     <Button\n *       theme={active ? \"primary\" : \"clear\"}\n *       themeType={active ? \"contained\" : \"flat\"}\n *       onClick={() => {\n *         data?.setActiveId(currentId);\n *       }}\n *       style={{ justifyContent: \"flex-start\" }}\n *     >\n *       {item.children}\n *     </Button>\n *   );\n * }\n *\n * function NestedNavigation(\n *   props: RenderRecursiveItemsProps<DefaultTreeItemNode, Data>\n * ): ReactElement {\n *   const {\n *     item,\n *     parents: _parents,\n *     // this is passed down from the root `RenderRecursively`\n *     data: _data,\n *     children,\n *   } = props;\n *   const { toggle, toggled: collapsed } = useToggle(false);\n *   const { elementProps } = useCollapseTransition({\n *     transitionIn: !collapsed,\n *   });\n *\n *   return (\n *     <li>\n *       <Button onClick={toggle}>{item.children}</Button>\n *       <List {...elementProps}>{children}</List>\n *     </li>\n *   );\n * }\n * ```\n *\n * @since 6.0.0\n */\nexport function RenderRecursively<Item, Data>(\n  props: RenderRecursivelyProps<Item, Data>\n): ReactElement {\n  const {\n    data,\n    items,\n    render: Render,\n    getItemKey = getRecursiveItemKey,\n    parents = [],\n  } = props;\n\n  return (\n    <>\n      {items.map((item, index) => {\n        let children: ReactNode;\n        const depth = parents.length;\n        if (item.items?.length) {\n          children = (\n            <RenderRecursively\n              data={data}\n              items={item.items}\n              render={Render}\n              getItemKey={getItemKey}\n              parents={[...parents, item]}\n            />\n          );\n        }\n\n        return (\n          <Render\n            key={getItemKey({ item, depth, index })}\n            // typecast since it should be undefined in renderer as well?\n            data={data}\n            item={item}\n            parents={parents}\n          >\n            {children}\n          </Render>\n        );\n      })}\n    </>\n  );\n}\n"],"names":["getRecursiveItemKey","options","depth","index","RenderRecursively","props","data","items","render","Render","getItemKey","parents","map","item","children","length"],"mappings":"AAAA,oDAAoD;;AAmBpD;;;;;;;;CAQC,GACD,OAAO,SAASA,oBACdC,OAAsC;IAEtC,MAAM,EAAEC,KAAK,EAAEC,KAAK,EAAE,GAAGF;IAEzB,OAAO,GAAGC,MAAM,CAAC,EAAEC,OAAO;AAC5B;AAoEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiJC,GACD,OAAO,SAASC,kBACdC,KAAyC;IAEzC,MAAM,EACJC,IAAI,EACJC,KAAK,EACLC,QAAQC,MAAM,EACdC,aAAaV,mBAAmB,EAChCW,UAAU,EAAE,EACb,GAAGN;IAEJ,qBACE;kBACGE,MAAMK,GAAG,CAAC,CAACC,MAAMV;YAChB,IAAIW;YACJ,MAAMZ,QAAQS,QAAQI,MAAM;YAC5B,IAAIF,KAAKN,KAAK,EAAEQ,QAAQ;gBACtBD,yBACE,KAACV;oBACCE,MAAMA;oBACNC,OAAOM,KAAKN,KAAK;oBACjBC,QAAQC;oBACRC,YAAYA;oBACZC,SAAS;2BAAIA;wBAASE;qBAAK;;YAGjC;YAEA,qBACE,KAACJ;gBAEC,6DAA6D;gBAC7DH,MAAMA;gBACNO,MAAMA;gBACNF,SAASA;0BAERG;eANIJ,WAAW;gBAAEG;gBAAMX;gBAAOC;YAAM;QAS3C;;AAGN"}

package/dist/utils/alphaNumericSort.d.ts

@@ -1,18 +1,22 @@
-import type { TextExtractor } from "../types.js";
+import { type TextExtractor } from "../types.js";
+/** @since 6.0.0 */
+export declare const DEFAULT_COLLATOR_OPTIONS: {
+    readonly numeric: true;
+    readonly caseFirst: "upper";
+};
 /**
  * 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 declare const DEFAULT_COLLATOR: Intl.Collator;
-/** @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;
@@ -20,12 +24,11 @@ export interface AlphaNumericSortOptions<T> {
      *
      * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];
      *
-     * `alphaNumericSort(items, {
-     *   extractor: item => item.name,
-     * })`
+     * alphaNumericSort(items, {
+     *   extractor: (item) => item.name,
+     * });
      * ```
      *
-     * @remarks
      * For javascript developers, this will throw an error in dev mode if an
      * extractor is not provided for non-string lists.
      *
@@ -37,8 +40,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,
@@ -54,7 +56,7 @@ export interface AlphaNumericSortOptions<T> {
      * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
      * @defaultValue `new Intl.Collator("en-US", { numeric: true, caseFirst: "upper" }).compare`
      */
-    compare?(a: string, b: string): number;
+    compare?: (a: string, b: string) => number;
     /**
      * Setting this to `true` will return the list in descending order instead of
      * ascending.
@@ -64,8 +66,7 @@ export interface AlphaNumericSortOptions<T> {
     descending?: boolean;
 }
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```ts
  * const items = ["World", "Hello"];
  *
@@ -78,8 +79,7 @@ export interface AlphaNumericSortOptions<T> {
  */
 export declare function alphaNumericSort<T extends string>(list: readonly T[], options?: Omit<AlphaNumericSortOptions<T>, "extractor">): readonly T[];
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```ts
  * interface Item {
  *   name: string;
@@ -88,7 +88,7 @@ export declare function alphaNumericSort<T extends string>(list: readonly T[], o
  * const items: Item[] = [{ name: "World" }, { name: "Hello" }];
  *
  * const sorted = alphaNumericSort(items, {
- *   extractor: item => item.name,
+ *   extractor: (item) => item.name,
  * });
  * // sorted == [{ name: "Hello" }, { name: "World" }]
  * ```

package/dist/utils/alphaNumericSort.js

@@ -1,23 +1,16 @@
-const identity = (item)=>{
-    if (typeof item === "string") {
-        return item;
-    }
-    if (process.env.NODE_ENV !== "production") {
-        throw new Error("A `TextExtractor` must be provided to `alphaNumericSort` for lists that do not contain strings");
-    }
-    return "";
+import { defaultExtractor } from "../searching/utils.js";
+/** @since 6.0.0 */ export const DEFAULT_COLLATOR_OPTIONS = {
+    numeric: true,
+    caseFirst: "upper"
 };
 /**
  * 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
- */ export const DEFAULT_COLLATOR = new Intl.Collator("en-US", {
-    numeric: true,
-    caseFirst: "upper"
-});
+ * @since 6.0.0
+ */ export const DEFAULT_COLLATOR = new Intl.Collator("en-US", DEFAULT_COLLATOR_OPTIONS);
 export function alphaNumericSort(list, options = {}) {
-    const { compare = DEFAULT_COLLATOR.compare, extractor = identity, descending = false } = options;
+    const { compare = DEFAULT_COLLATOR.compare, extractor = defaultExtractor("alphaNumericSort"), descending = false } = options;
     const sorted = list.slice();
     sorted.sort((a, b)=>{
         const aValue = extractor(a);

package/dist/utils/alphaNumericSort.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/alphaNumericSort.ts"],"sourcesContent":["import type { TextExtractor } from \"../types.js\";\n\nconst identity = <T>(item: T): string => {\n  if (typeof item === \"string\") {\n    return item;\n  }\n\n  if (process.env.NODE_ENV !== \"production\") {\n    throw new Error(\n      \"A `TextExtractor` must be provided to `alphaNumericSort` for lists that do not contain strings\"\n    );\n  }\n\n  return \"\";\n};\n\n/**\n * The default `Intl.Collator` that should be used for sorting large lists.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare#performance\n * @remarks \\@since 6.0.0\n */\nexport const DEFAULT_COLLATOR = new Intl.Collator(\"en-US\", {\n  numeric: true,\n  caseFirst: \"upper\",\n});\n\n/** @remarks \\@since 6.0.0 */\nexport interface AlphaNumericSortOptions<T> {\n  /**\n   * The extractor is only required when the list of items are not strings.\n   *\n   * @example\n   * Simple Example\n   * ```ts\n   * interface Item {\n   *   name: string;\n   * }\n   *\n   * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];\n   *\n   * `alphaNumericSort(items, {\n   *   extractor: item => item.name,\n   * })`\n   * ```\n   *\n   * @remarks\n   * For javascript developers, this will throw an error in dev mode if an\n   * extractor is not provided for non-string lists.\n   *\n   * @defaultValue `typeof item === \"string\" ? item : \"\"`\n   */\n  extractor?: TextExtractor<T>;\n\n  /**\n   * A custom compare function for sorting the list. This should really only be\n   * provided if the language for your app is not `\"en-US\"` or you'd like to\n   * provide some custom sorting options.\n   *\n   * @example\n   * Custom Compare using Intl.Collator\n   * ```ts\n   * const collator = new Intl.Collator(\"en-US\", {\n   *   numeric: false,\n   *   caseFirst: \"lower\",\n   *   usage: \"search\",\n   * });\n   *\n   * alphaNumericSort(items, {\n   *   compare: collator.compare,\n   * })\n   * ```\n   *\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator\n   * @defaultValue `new Intl.Collator(\"en-US\", { numeric: true, caseFirst: \"upper\" }).compare`\n   */\n  compare?(a: string, b: string): number;\n\n  /**\n   * Setting this to `true` will return the list in descending order instead of\n   * ascending.\n   *\n   * @defaultValue `false`\n   */\n  descending?: boolean;\n}\n\n/**\n * @example\n * Simple Example\n * ```ts\n * const items = [\"World\", \"Hello\"];\n *\n * const sorted = alphaNumericSort(items);\n * // sorted == [\"Hello\", \"World\"]\n * ```\n *\n * @param list - The list of strings to sort\n * @returns a new sorted list\n */\nexport function alphaNumericSort<T extends string>(\n  list: readonly T[],\n  options?: Omit<AlphaNumericSortOptions<T>, \"extractor\">\n): readonly T[];\n/**\n * @example\n * Simple Example\n * ```ts\n * interface Item {\n *   name: string;\n * }\n *\n * const items: Item[] = [{ name: \"World\" }, { name: \"Hello\" }];\n *\n * const sorted = alphaNumericSort(items, {\n *   extractor: item => item.name,\n * });\n * // sorted == [{ name: \"Hello\" }, { name: \"World\" }]\n * ```\n *\n * @param list - The list of items to sort\n * @returns a new sorted list\n */\nexport function alphaNumericSort<T>(\n  list: readonly T[],\n  options: AlphaNumericSortOptions<T> & { extractor: TextExtractor<T> }\n): readonly T[];\nexport function alphaNumericSort<T>(\n  list: readonly T[],\n  options: AlphaNumericSortOptions<T> = {}\n): readonly T[] {\n  const {\n    compare = DEFAULT_COLLATOR.compare,\n    extractor = identity,\n    descending = false,\n  } = options;\n\n  const sorted = list.slice();\n  sorted.sort((a, b) => {\n    const aValue = extractor(a);\n    const bValue = extractor(b);\n\n    const value1 = descending ? bValue : aValue;\n    const value2 = descending ? aValue : bValue;\n\n    return compare(value1, value2);\n  });\n\n  return sorted;\n}\n"],"names":["identity","item","process","env","NODE_ENV","Error","DEFAULT_COLLATOR","Intl","Collator","numeric","caseFirst","alphaNumericSort","list","options","compare","extractor","descending","sorted","slice","sort","a","b","aValue","bValue","value1","value2"],"mappings":"AAEA,MAAMA,WAAW,CAAIC;IACnB,IAAI,OAAOA,SAAS,UAAU;QAC5B,OAAOA;IACT;IAEA,IAAIC,QAAQC,GAAG,CAACC,QAAQ,KAAK,cAAc;QACzC,MAAM,IAAIC,MACR;IAEJ;IAEA,OAAO;AACT;AAEA;;;;;CAKC,GACD,OAAO,MAAMC,mBAAmB,IAAIC,KAAKC,QAAQ,CAAC,SAAS;IACzDC,SAAS;IACTC,WAAW;AACb,GAAG;AAsGH,OAAO,SAASC,iBACdC,IAAkB,EAClBC,UAAsC,CAAC,CAAC;IAExC,MAAM,EACJC,UAAUR,iBAAiBQ,OAAO,EAClCC,YAAYf,QAAQ,EACpBgB,aAAa,KAAK,EACnB,GAAGH;IAEJ,MAAMI,SAASL,KAAKM,KAAK;IACzBD,OAAOE,IAAI,CAAC,CAACC,GAAGC;QACd,MAAMC,SAASP,UAAUK;QACzB,MAAMG,SAASR,UAAUM;QAEzB,MAAMG,SAASR,aAAaO,SAASD;QACrC,MAAMG,SAAST,aAAaM,SAASC;QAErC,OAAOT,QAAQU,QAAQC;IACzB;IAEA,OAAOR;AACT"}
+{"version":3,"sources":["../../src/utils/alphaNumericSort.ts"],"sourcesContent":["import { defaultExtractor } from \"../searching/utils.js\";\nimport { type TextExtractor } from \"../types.js\";\n\n/** @since 6.0.0 */\nexport const DEFAULT_COLLATOR_OPTIONS = {\n  numeric: true,\n  caseFirst: \"upper\",\n} as const satisfies Intl.CollatorOptions;\n\n/**\n * The default `Intl.Collator` that should be used for sorting large lists.\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare#performance\n * @since 6.0.0\n */\nexport const DEFAULT_COLLATOR = new Intl.Collator(\n  \"en-US\",\n  DEFAULT_COLLATOR_OPTIONS\n);\n\n/** @since 6.0.0 */\nexport interface AlphaNumericSortOptions<T> {\n  /**\n   * The extractor is only required when the list of items are not strings.\n   *\n   * @example Simple Example\n   * ```ts\n   * interface Item {\n   *   name: string;\n   * }\n   *\n   * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];\n   *\n   * alphaNumericSort(items, {\n   *   extractor: (item) => item.name,\n   * });\n   * ```\n   *\n   * For javascript developers, this will throw an error in dev mode if an\n   * extractor is not provided for non-string lists.\n   *\n   * @defaultValue `typeof item === \"string\" ? item : \"\"`\n   */\n  extractor?: TextExtractor<T>;\n\n  /**\n   * A custom compare function for sorting the list. This should really only be\n   * provided if the language for your app is not `\"en-US\"` or you'd like to\n   * provide some custom sorting options.\n   *\n   * @example Custom Compare using Intl.Collator\n   * ```ts\n   * const collator = new Intl.Collator(\"en-US\", {\n   *   numeric: false,\n   *   caseFirst: \"lower\",\n   *   usage: \"search\",\n   * });\n   *\n   * alphaNumericSort(items, {\n   *   compare: collator.compare,\n   * })\n   * ```\n   *\n   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator\n   * @defaultValue `new Intl.Collator(\"en-US\", { numeric: true, caseFirst: \"upper\" }).compare`\n   */\n  compare?: (a: string, b: string) => number;\n\n  /**\n   * Setting this to `true` will return the list in descending order instead of\n   * ascending.\n   *\n   * @defaultValue `false`\n   */\n  descending?: boolean;\n}\n\n/**\n * @example Simple Example\n * ```ts\n * const items = [\"World\", \"Hello\"];\n *\n * const sorted = alphaNumericSort(items);\n * // sorted == [\"Hello\", \"World\"]\n * ```\n *\n * @param list - The list of strings to sort\n * @returns a new sorted list\n */\nexport function alphaNumericSort<T extends string>(\n  list: readonly T[],\n  options?: Omit<AlphaNumericSortOptions<T>, \"extractor\">\n): readonly T[];\n/**\n * @example Simple Example\n * ```ts\n * interface Item {\n *   name: string;\n * }\n *\n * const items: Item[] = [{ name: \"World\" }, { name: \"Hello\" }];\n *\n * const sorted = alphaNumericSort(items, {\n *   extractor: (item) => item.name,\n * });\n * // sorted == [{ name: \"Hello\" }, { name: \"World\" }]\n * ```\n *\n * @param list - The list of items to sort\n * @returns a new sorted list\n */\nexport function alphaNumericSort<T>(\n  list: readonly T[],\n  options: AlphaNumericSortOptions<T> & { extractor: TextExtractor<T> }\n): readonly T[];\nexport function alphaNumericSort<T>(\n  list: readonly T[],\n  options: AlphaNumericSortOptions<T> = {}\n): readonly T[] {\n  const {\n    compare = DEFAULT_COLLATOR.compare,\n    extractor = defaultExtractor(\"alphaNumericSort\"),\n    descending = false,\n  } = options;\n\n  const sorted = list.slice();\n  sorted.sort((a, b) => {\n    const aValue = extractor(a);\n    const bValue = extractor(b);\n\n    const value1 = descending ? bValue : aValue;\n    const value2 = descending ? aValue : bValue;\n\n    return compare(value1, value2);\n  });\n\n  return sorted;\n}\n"],"names":["defaultExtractor","DEFAULT_COLLATOR_OPTIONS","numeric","caseFirst","DEFAULT_COLLATOR","Intl","Collator","alphaNumericSort","list","options","compare","extractor","descending","sorted","slice","sort","a","b","aValue","bValue","value1","value2"],"mappings":"AAAA,SAASA,gBAAgB,QAAQ,wBAAwB;AAGzD,iBAAiB,GACjB,OAAO,MAAMC,2BAA2B;IACtCC,SAAS;IACTC,WAAW;AACb,EAA0C;AAE1C;;;;;CAKC,GACD,OAAO,MAAMC,mBAAmB,IAAIC,KAAKC,QAAQ,CAC/C,SACAL,0BACA;AAiGF,OAAO,SAASM,iBACdC,IAAkB,EAClBC,UAAsC,CAAC,CAAC;IAExC,MAAM,EACJC,UAAUN,iBAAiBM,OAAO,EAClCC,YAAYX,iBAAiB,mBAAmB,EAChDY,aAAa,KAAK,EACnB,GAAGH;IAEJ,MAAMI,SAASL,KAAKM,KAAK;IACzBD,OAAOE,IAAI,CAAC,CAACC,GAAGC;QACd,MAAMC,SAASP,UAAUK;QACzB,MAAMG,SAASR,UAAUM;QAEzB,MAAMG,SAASR,aAAaO,SAASD;QACrC,MAAMG,SAAST,aAAaM,SAASC;QAErC,OAAOT,QAAQU,QAAQC;IACzB;IAEA,OAAOR;AACT"}

package/dist/utils/applyRef.d.ts

@@ -3,8 +3,7 @@ import type { 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/dist/utils/applyRef.js

@@ -2,8 +2,7 @@
  * 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";