@react-md/core 1.0.0-next.12 → 1.0.0-next.14

package/src/layout/useLayoutWindowSplitter.ts

@@ -10,7 +10,7 @@ import {
 } from "../window-splitter/useWindowSplitter.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutWindowSplitterOptions
   extends Omit<WindowSplitterOptions, "min" | "max"> {
@@ -48,7 +48,7 @@ export interface LayoutWindowSplitterOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ProvidedLayoutWindowSplitterProps
   extends WindowSplitterWidgetProps<HTMLButtonElement> {
@@ -57,7 +57,7 @@ export interface ProvidedLayoutWindowSplitterProps
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutWindowSplitterImplementation
   extends WindowSplitterImplementation {
@@ -72,8 +72,7 @@ export interface LayoutWindowSplitterImplementation
  * Note: This will automatically save the width in local storage as
  * `"navWidth"`. See the example below if you do not want to use local storage.
  *
- * @example
- * Without this hook
+ * @example Without this hook
  * ```tsx
  * import { useWindowSize, useWindowSplitter } from "@react-md/core";
  * import type { ProvidedLayoutWindowSplitterProps } from "@react-md/core";
@@ -105,7 +104,7 @@ export interface LayoutWindowSplitterImplementation
  * ```
  *
  * @see {@link useResizableLayout} For a pre-built solution.
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useLayoutWindowSplitter(
   options: LayoutWindowSplitterOptions = {}

package/src/layout/useMainTabIndex.ts

@@ -5,7 +5,7 @@ import { useUserInteractionMode } from "../interaction/UserInteractionModeProvid
  * This hook is used to return a tab index of `-1` whenever the user is using a
  * keyboard for the `SkipToMainContent` to work correctly.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useMainTabIndex(tabIndex?: number): number | undefined {
   const keyboard = useUserInteractionMode() === "keyboard";

package/src/layout/useResizableLayout.ts

@@ -13,7 +13,7 @@ import {
 } from "./useLayoutWindowSplitter.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ResizableLayoutOptions
   extends ExpandableLayoutOptions,
@@ -28,7 +28,7 @@ export interface ResizableLayoutOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ProvidedResizableLayoutNavProps
   extends ProvidedLayoutNavProps {
@@ -36,7 +36,7 @@ export interface ProvidedResizableLayoutNavProps
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ResizableLayoutImplementation
   extends ExpandableLayoutImplementation {
@@ -45,8 +45,7 @@ export interface ResizableLayoutImplementation
 }
 
 /**
- * @example
- * Main USage
+ * @example Main Usage
  * ```tsx
  * import {
  *   AppBarTitle,
@@ -78,7 +77,7 @@ export interface ResizableLayoutImplementation
  *   const { pathname } = useHistory();
  *
  *   const {
- *     isPhone,
+ *     temporary,
  *     appBarProps,
  *     expandableNavProps,
  *     mainProps,
@@ -97,7 +96,7 @@ export interface ResizableLayoutImplementation
  *         <CustomNavigation />
  *       </LayoutNav>
  *       <LayoutWindowSplitter {...windowSplitterProps} />
- *       {isPhone && (
+ *       {temporary && (
  *         <Sheet {...temporaryNavProps}>
  *           <CustomNavigation />
  *         </Sheet>
@@ -107,7 +106,54 @@ export interface ResizableLayoutImplementation
  *   }
  * }
  * ```
- * @remarks \@since 6.0.0
+ *
+ * If you have a large navigation panel, you can conditionally render the
+ * `LayoutNav` with the `persistent` boolean returned by the hook which will
+ * ensure that the DOM has rehydrated before unmounting to prevent SSR errors.
+ *
+ * @example Conditionally Rendering
+ * ```diff
+ *   const {
+ *     temporary,
+ * +   persistent,
+ *     appBarProps,
+ *     expandableNavProps,
+ *     mainProps,
+ *     navToggleProps,
+ *     temporaryNavProps,
+ *     windowSplitterProps,
+ *   } = useResizableLayout({ pathname });
+ *
+ *   return {
+ *     <>
+ *       <LayoutAppBar {...appBarProps}>
+ *         <Button {...navToggleProps} />
+ *         <AppBarTitle>Hello, world!</AppBarTitle>
+ *       </LayoutAppBar>
+ * -     <LayoutNav {...expandableNavProps}>
+ * -       <CustomNavigation />
+ * -     </LayoutNav>
+ * -     <LayoutWindowSplitter {...windowSplitterProps} />
+ * +     {persistent && (
+ * +       <>
+ * +         <LayoutNav {...expandableNavProps}>
+ * +           <CustomNavigation />
+ * +         </LayoutNav>
+ * +         <LayoutWindowSplitter {...windowSplitterProps} />
+ * +       </>
+ * +     )}
+ *       {temporary && (
+ *         <Sheet {...temporaryNavProps}>
+ *           <CustomNavigation />
+ *         </Sheet>
+ *       )}
+ *       <Main {...mainProps}>{children}</Main>
+ *     </>
+ *   }
+ *
+ * ```
+ *
+ * @since 6.0.0
  */
 export function useResizableLayout(
   options: ResizableLayoutOptions

package/src/layout/useTemporaryLayout.ts

@@ -1,13 +1,12 @@
 "use client";
-import type { PropsWithChildren } from "react";
-import { useEffect } from "react";
-import type { AppBarProps } from "../app-bar/AppBar.js";
-import type { ButtonProps } from "../button/Button.js";
+import { useEffect, type PropsWithChildren } from "react";
+import { type AppBarProps } from "../app-bar/AppBar.js";
+import { type ButtonProps } from "../button/Button.js";
 import { getIcon } from "../icon/iconConfig.js";
-import type { SheetProps } from "../sheet/Sheet.js";
-import type { CssPosition, UseStateInitializer } from "../types.js";
+import { type SheetProps } from "../sheet/Sheet.js";
+import { type CssPosition, type UseStateInitializer } from "../types.js";
 import { useToggle } from "../useToggle.js";
-import type { MainProps } from "./Main.js";
+import { type MainProps } from "./Main.js";
 
 export interface TemporaryLayoutOptions {
   /**
@@ -24,14 +23,14 @@ export interface TemporaryLayoutOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedLayoutNavToggleProps = PropsWithChildren<
   Pick<Required<ButtonProps>, "aria-label" | "buttonType" | "onClick">
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedTemporaryLayoutNavProps = Pick<
   Required<SheetProps>,
@@ -39,21 +38,21 @@ export type ProvidedTemporaryLayoutNavProps = Pick<
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedTemporaryLayoutMainProps = Required<
   Pick<MainProps, "appBarOffset">
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedTemporaryLayoutAppBarProps = Required<
   Pick<AppBarProps, "position">
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface TemporaryLayoutImplementation {
   visible: boolean;
@@ -116,7 +115,7 @@ export interface TemporaryLayoutImplementation {
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useTemporaryLayout(
   options: TemporaryLayoutOptions

package/src/link/Link.tsx

@@ -14,7 +14,7 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type CustomLinkComponent =
   | ForwardRefExoticComponent<{ href: string }>
@@ -22,13 +22,12 @@ export type CustomLinkComponent =
   | "a";
 
 /**
- * @remarks
- * \@since 6.0.0 Removed the `preventMaliciousTarget` prop since browsers
+ * @since 6.0.0 Removed the `preventMaliciousTarget` prop since browsers
  * default to `rel=noopener` after updating the {@link https://github.com/whatwg/html/issues/4078|spec}.
- * \@since 6.0.0 Removed the `component` prop since all you need for link
+ * @since 6.0.0 Removed the `component` prop since all you need for link
  * behavior is `className="rmd-link"`.
- * \@since 6.0.0 The `href` prop is required.
- * \@since 6.0.0 Removed the `flexCentered` prop since it is now the default
+ * @since 6.0.0 The `href` prop is required.
+ * @since 6.0.0 Removed the `flexCentered` prop since it is now the default
  * styles.
  */
 export interface LinkProps
@@ -52,8 +51,7 @@ export interface LinkProps
 /**
  * **Server Component**
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { Link, Typography } from "@react-md/core";
  * import type { ReactElement } from "react";
@@ -69,13 +67,12 @@ export interface LinkProps
  * ```
  *
  *
- * @remarks
- * \@since 6.0.0 Removed the `preventMaliciousTarget` prop since browsers
+ * @since 6.0.0 Removed the `preventMaliciousTarget` prop since browsers
  * default to `rel=noopener` after updating the {@link https://github.com/whatwg/html/issues/4078|spec}.
- * \@since 6.0.0 Removed the `component` prop since all you need for link
+ * @since 6.0.0 Removed the `component` prop since all you need for link
  * behavior is `className="rmd-link"`.
- * \@since 6.0.0 The `href` prop is required.
- * \@since 6.0.0 Removed the `flexCentered` prop since it is now the default
+ * @since 6.0.0 The `href` prop is required.
+ * @since 6.0.0 Removed the `flexCentered` prop since it is now the default
  * styles.
  */
 export const Link = forwardRef<HTMLAnchorElement, LinkProps>(

package/src/link/SkipToMainContent.tsx

@@ -16,8 +16,7 @@ const getMainElement = (mainId: string): HTMLElement | null =>
     : document.querySelector<HTMLElement>('main,[role="main"]');
 
 /**
- * @remarks
- * \@since 6.0.0 The {@link mainId} is optional
+ * @since 6.0.0 The {@link mainId} is optional
  */
 export interface SkipToMainContentProps
   extends Omit<LinkProps, "href">,
@@ -43,8 +42,7 @@ export interface SkipToMainContentProps
 /**
  * **Client Component**
  *
- * @remarks
- * \@since 6.0.0 Throws an error after rendering if no main element can be found
+ * @since 6.0.0 Throws an error after rendering if no main element can be found
  * with the provided `mainId` in development mode. The previous behavior would
  * only log an error after being clicked.
  */

package/src/link/styles.ts

@@ -3,7 +3,7 @@ import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-link");
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface LinkClassNameOptions {
   className?: string;
 
@@ -15,7 +15,7 @@ export interface LinkClassNameOptions {
  * This really doesn't do much at this time since it only merges `rmd-link` with
  * the optional className. This was mostly added just for convention purposes.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function link(options: LinkClassNameOptions = {}): string {
   const { flex, className } = options;
@@ -23,7 +23,7 @@ export function link(options: LinkClassNameOptions = {}): string {
   return cnb(styles({ flex }), className);
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface SKipToMainContentClassNameOptions {
   className?: string;
 
@@ -34,7 +34,7 @@ export interface SKipToMainContentClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function skipToMainContent(
   options: SKipToMainContentClassNameOptions = {}

package/src/list/List.tsx

@@ -11,7 +11,7 @@ declare module "react" {
 
 const styles = bem("rmd-list");
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListClassNameOptions {
   className?: string;
 
@@ -23,7 +23,7 @@ export interface ListClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function list(options: ListClassNameOptions = {}): string {
   const { dense = false, horizontal = false, className } = options;
@@ -69,8 +69,7 @@ export interface ListProps extends HTMLAttributes<ListElement> {
  * The `List` component is used to render a collection of clickable actions
  * vertically or horizontally and does not include the default `ol`/`ul` styles.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { List, ListItem, ListItemLink } from "@react-md/core";
  * import type { ReactElement } from "react";

package/src/list/ListItem.tsx

@@ -25,7 +25,7 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0 Renamed `threeLines` to `multiline` since it can
+ * @since 6.0.0 Renamed `threeLines` to `multiline` since it can
  * support more than three lines of text.
  */
 export interface ListItemProps
@@ -61,7 +61,7 @@ export interface ListItemProps
    * Note: This does nothing if the `disabled` prop is not enabled.
    *
    * @defaultValue `false`
-   * @remarks \@since 2.4.3
+   * @since 2.4.3
    */
   disabledOpacity?: boolean;
 
@@ -81,8 +81,7 @@ export interface ListItemProps
  * The `ListItem` is used to create a clickable/focusable button within a
  * `List` and removes the normal `<li>` styles.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { List, ListItem } from "@react-md/core";
  * import type { ReactElement  } from "react";
@@ -111,8 +110,7 @@ export interface ListItemProps
  * }
  * ```
  *
- * @example
- * Applying Addons Example
+ * @example Applying Addons Example
  * ```tsx
  * import { List, ListItem } from "@react-md/core";
  * import FavoriteIcon from "@react-md/material-icons/FavoriteIcon";

package/src/list/ListItemChildren.tsx

@@ -16,8 +16,7 @@ import { type ListItemChildrenProps } from "./types.js";
  * in a DOM node for styling. The parent component should normally have
  * `display: flex` for the styling to work.
  *
- * @example
- * Custom Component Usage
+ * @example Custom Component Usage
  * ```tsx
  * import { ListItemChildren } from "@react-md/core";
  * import FavoriteIcon from "@react-md/material-icons/FavoriteIcon";

package/src/list/ListSubheader.tsx

@@ -6,7 +6,7 @@ import { ListItemText } from "./ListItemText.js";
 
 const styles = bem("rmd-list-subheader");
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListSubheaderClassNameOptions {
   className?: string;
 
@@ -20,7 +20,7 @@ export interface ListSubheaderClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function listSubheader(
   options: ListSubheaderClassNameOptions = {}
@@ -39,7 +39,7 @@ export interface ListSubheaderProps
   role?: HTMLAttributes<HTMLLIElement>["role"];
 
   /**
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   textProps?: PropsWithRef<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>;
 }

package/src/list/getListItemHeight.ts

@@ -1,7 +1,7 @@
 import type { ListItemChildrenProps, ListItemHeight } from "./types.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface ListItemHeightOptions

package/src/list/listItemStyles.ts

@@ -9,7 +9,7 @@ import type {
 
 const styles = bem("rmd-list-item");
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListItemClassNameOptions {
   className?: string;
   /**
@@ -32,7 +32,7 @@ export interface ListItemClassNameOptions {
    * Note: This does nothing if the `disabled` prop is not enabled.
    *
    * @defaultValue `false`
-   * @remarks \@since 2.4.3
+   * @since 2.4.3
    */
   disabledOpacity?: boolean;
 
@@ -46,7 +46,7 @@ export interface ListItemClassNameOptions {
   clickable?: boolean;
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface InternalListItemClassNameOptions
   extends ListItemClassNameOptions {
   /**
@@ -62,7 +62,7 @@ export interface InternalListItemClassNameOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function listItem(
   options: InternalListItemClassNameOptions = {}
@@ -92,7 +92,7 @@ export function listItem(
   );
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListItemTextClassNameOptions {
   className?: string;
   /**
@@ -107,7 +107,7 @@ export interface ListItemTextClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function listItemText(
   options: ListItemTextClassNameOptions = {}
@@ -123,7 +123,7 @@ export function listItemText(
   );
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListItemAddonClassNameOptions {
   className?: string;
 
@@ -159,7 +159,7 @@ export interface ListItemAddonClassNameOptions {
    * When this is set to `true`, the flex styles will not be applied.
    *
    * @defaultValue `false`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   disableCenteredMedia?: boolean;
 
@@ -175,7 +175,7 @@ export interface ListItemAddonClassNameOptions {
 
 /**
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function listItemAddon(
   options: ListItemAddonClassNameOptions = {}

package/src/list/types.ts

@@ -22,7 +22,7 @@ export type ListItemHeight =
 export type ListItemAddonPosition = "top" | "middle" | "bottom";
 export type ListItemAddonType = "icon" | "avatar" | "media" | "large-media";
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ListItemChildrenAddonProps {
   /**
    * An optional addon to display to the left of the `primaryText` or
@@ -48,7 +48,7 @@ export interface ListItemChildrenAddonProps {
   leftAddonPosition?: ListItemAddonPosition;
 
   /**
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   leftAddonClassName?: string;
 
@@ -57,7 +57,7 @@ export interface ListItemChildrenAddonProps {
    * apply the correct styling.
    *
    * @defaultValue `leftAddonType === "media" || leftAddonType === "large-media"`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   leftAddonForceWrap?: boolean;
 
@@ -94,7 +94,7 @@ export interface ListItemChildrenAddonProps {
   rightAddonPosition?: ListItemAddonPosition;
 
   /**
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   rightAddonClassName?: string;
 
@@ -103,7 +103,7 @@ export interface ListItemChildrenAddonProps {
    * apply the correct styling.
    *
    * @defaultValue `rightAddonType === "media" || rightAddonType === "large-media"`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   rightAddonForceWrap?: boolean;
 
@@ -118,7 +118,7 @@ export interface ListItemChildrenAddonProps {
    * When this is set to `true`, the flex styles will not be applied.
    *
    * @defaultValue `false`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   disableLeftAddonCenteredMedia?: boolean;
 
@@ -133,7 +133,7 @@ export interface ListItemChildrenAddonProps {
    * When this is set to `true`, the flex styles will not be applied.
    *
    * @defaultValue `false`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   disableRightAddonCenteredMedia?: boolean;
 }
@@ -143,7 +143,7 @@ export interface ListItemChildrenAddonProps {
  * {@link ListItemChildrenAddonProps} with renamed versions but should still
  * support everything for rendering text.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ListItemChildrenTextProps {
   /**
@@ -157,7 +157,7 @@ export interface ListItemChildrenTextProps {
    * Any additional props that should be passed to the `<span>` surrounding
    * the {@link children}, {@link primaryText}, and {@link secondaryText}.
    *
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   textProps?: PropsWithRef<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>;
 
@@ -177,7 +177,7 @@ export interface ListItemChildrenTextProps {
    * Set this to `true` if the {@link children} should not automatically be
    * wrapped in the `ListItemText` component.
    *
-   * @remarks \@since 6.0.0 Renamed from `textChildren` since it was defaulted on.
+   * @since 6.0.0 Renamed from `textChildren` since it was defaulted on.
    * @defaultValue `false`
    */
   disableTextChildren?: boolean;
@@ -203,7 +203,7 @@ export interface ListItemChildrenTextProps {
    * Any additional props that should be passed to the `<span>` surrounding
    * the {@link secondaryText}.
    *
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   secondaryTextProps?: PropsWithRef<
     HTMLAttributes<HTMLSpanElement>,

package/src/media-queries/AppSizeProvider.tsx

@@ -40,8 +40,7 @@ const { Provider } = context;
  * **Note**: The app size object returned by this hook will **not** be equal
  * between renders.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { useAppSize } from "@react-md/core";
  *

package/src/media-queries/useMediaQuery.ts

@@ -3,8 +3,7 @@ import { useEffect, useState } from "react";
 import { useSsr } from "../SsrProvider.js";
 
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { useMediaQuery } from "@react-md/core";
  * import type { ReactElement } from "react";
@@ -20,7 +19,7 @@ import { useSsr } from "../SsrProvider.js";
  * @param disabled - When `true`, the `window.matchMedia` API will not be
  * activated and the hook will always return `false`.
  * @returns `true` if the media query matches
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useMediaQuery(query: string, disabled = false): boolean {
   const ssr = useSsr();