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

package/src/interaction/useHigherContrastChildren.tsx

@@ -12,8 +12,7 @@ import { INTERACTION_CONFIG } from "./config.js";
  * Note: This should generally be used with the {@link useElementInteraction}
  * hook.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import {
  *   useElementInteraction,
@@ -66,7 +65,7 @@ import { INTERACTION_CONFIG } from "./config.js";
  * contrast mode is enabled. This is really used within `ListItem`s so there
  * aren't unneeded `<span>`s for string/number children when there are addons.
  * @returns the children to render
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export function useHigherContrastChildren(

package/src/layout/LayoutAppBar.tsx

@@ -15,7 +15,7 @@ import { useEnsuredId } from "../useEnsuredId.js";
 import { useLayoutAppBarHeight } from "./useLayoutAppBarHeight.js";
 
 /**
- * @remarks \@since 6.0.0 Only supports `AppBar` + `SkipToMainContent` props
+ * @since 6.0.0 Only supports `AppBar` + `SkipToMainContent` props
  */
 export interface LayoutAppBarProps extends AppBarProps {
   /** @defaultValue `"header"` */
@@ -38,8 +38,7 @@ export interface LayoutAppBarProps extends AppBarProps {
  * javascript bundle size, it is recommended to configure this variable in SCSS
  * instead.
  *
- * @example
- * Static Height
+ * @example Static Height
  * ```scss
  * @use "everything";
  *
@@ -48,8 +47,7 @@ export interface LayoutAppBarProps extends AppBarProps {
  * }
  * ```
  *
- * @example
- * Media Query Height Changes
+ * @example Media Query Height Changes
  * ```scss
  * @use "everything";
  *
@@ -61,8 +59,7 @@ export interface LayoutAppBarProps extends AppBarProps {
  * }
  * ```
  *
- * @remarks
- * \@since 6.0.0 This component no longer renders the `LayoutNavToggle` and
+ * @since 6.0.0 This component no longer renders the `LayoutNavToggle` and
  * `LayoutAppBarTitle` since they no longer exist. The only purpose of this
  * component is to dynamically set the `--rmd-layout-header-height` variable.
  */

package/src/layout/LayoutNav.tsx

@@ -16,7 +16,7 @@ import { useCSSTransition } from "../transition/useCSSTransition.js";
 import { layoutNav } from "./layoutNavStyles.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutNavProps
   extends HTMLAttributes<HTMLDivElement>,
@@ -59,8 +59,7 @@ export interface LayoutNavProps
  * `LayoutWindowSplitter` and expandable layouts. Do not use this component for
  * temporary navigation and instead use a `Sheet`.
  *
- * @example
- * Full Height Layout
+ * @example Full Height Layout
  * ```tsx
  * "use client";
  * import {
@@ -92,8 +91,7 @@ export interface LayoutNavProps
  * }
  * ```
  *
- * @example
- * Toggleable Layout
+ * @example Toggleable Layout
  * ```tsx
  * "use client";
  * import {
@@ -135,7 +133,7 @@ export interface LayoutNavProps
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const LayoutNav = forwardRef<HTMLDivElement, LayoutNavProps>(
   function LayoutNav(props, ref) {

package/src/layout/LayoutWindowSplitter.tsx

@@ -13,7 +13,7 @@ import {
 } from "./layoutWindowSplitterStyles.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutWindowSplitterProps
   extends WindowSplitterWidgetProps<HTMLButtonElement>,
@@ -39,8 +39,7 @@ export interface LayoutWindowSplitterProps
  * @see {@link useResizableExpandableLayout} for a default implementation for
  * this component.
  *
- * @example
- * Dynamic Resizing
+ * @example Dynamic Resizing
  * ```tsx
  * import {
  *   LayoutNav,
@@ -90,7 +89,7 @@ export interface LayoutWindowSplitterProps
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const LayoutWindowSplitter = forwardRef<
   HTMLButtonElement,

package/src/layout/Main.tsx

@@ -11,7 +11,7 @@ import { main, type MainClassNameOptions } from "./mainStyles.js";
 import { useMainTabIndex } from "./useMainTabIndex.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type CustomMainElement = ElementType<
   HTMLAttributes<HTMLElement> & {
@@ -22,7 +22,7 @@ export type CustomMainElement = ElementType<
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface MainProps
   extends HTMLAttributes<HTMLElement>,
@@ -42,8 +42,7 @@ export interface MainProps
  * to work correctly. If you don't need that functionality, use the {@link main}
  * style utility instead.
  *
- * @example
- * Styles Only
+ * @example Styles Only
  * ```tsx
  * import { main as mainStyles } from "@react-md/core":
  *
@@ -61,7 +60,7 @@ export interface MainProps
  * }
  * ```
  *
- * @remarks \@since 6.0.0 Renamed from `LayoutMain` removed a lot of
+ * @since 6.0.0 Renamed from `LayoutMain` removed a lot of
  * functionality to keep this component simple.
  */
 export const Main = forwardRef<HTMLElement, MainProps>(

package/src/layout/__tests__/LayoutAppBar.tsx

@@ -68,7 +68,30 @@ describe("LayoutAppBar", () => {
     rmdRender(<Test />);
 
     expect(getVar()).toBe("0px");
+
+    const appBar = screen.getByRole("banner");
+    act(() => {
+      observer.resizeElement(appBar, {
+        height: 96,
+      });
+    });
+    expect(getVar()).toBe("96px");
+  });
+
+  it("should automatically apply the app bar height as css variables while waiting for the first observer event to prevent layout shifts", () => {
+    const observer = setupResizeObserverMock();
+    // pretend it was set in CSS
+    const getComputedStyle = jest
+      .spyOn(window, "getComputedStyle")
+      .mockReturnValue({
+        getPropertyValue: () => "3.5rem",
+      } as unknown as CSSStyleDeclaration);
+    rmdRender(<Test />);
+
+    expect(getVar()).toBe("3.5rem");
+
     const appBar = screen.getByRole("banner");
+    getComputedStyle.mockRestore();
     act(() => {
       observer.resizeElement(appBar, {
         height: 96,

package/src/layout/__tests__/useExpandableLayout.tsx

@@ -267,5 +267,13 @@ describe("useExpandableLayout", () => {
 
     matchMediaSpy.changeViewport(matchDesktop);
     expect(temporaryNav).not.toBeInTheDocument();
+
+    matchMediaSpy.mockRestore();
+  });
+
+  it("should allow for a static full height nav which will be hidden based on media queries", () => {
+    rmdRender(<Layout fullHeightNav="static" defaultVisible />);
+    const navToggle = screen.getByRole("button", { name: "Navigation" });
+    expect(navToggle).toHaveClass("rmd-layout-nav-toggle");
   });
 });

package/src/layout/_layout.scss

@@ -13,6 +13,7 @@
 
 $disable-everything: false !default;
 $disable-resizable: false !default;
+$disable-full-height-navigation: false !default;
 
 $main-focus-z-index: 999 !default;
 
@@ -93,8 +94,10 @@ $variables: (size, header-height);
       .rmd-layout-nav {
         @include sheet.set-var(width, get-var(size));
         @include media-queries.media($navigation-breakpoint) {
+          // Why did I want grid? flex seems easier atm
           // use grid so that you can easily have a header + tree that fills the remaining space
-          display: grid;
+          display: flex;
+          flex-direction: column;
         }
 
         container: $navigation-container-name;
@@ -106,6 +109,14 @@ $variables: (size, header-height);
         }
       }
 
+      @if not $disable-full-height-navigation {
+        .rmd-layout-nav-toggle {
+          @include media-queries.media($navigation-breakpoint) {
+            display: none;
+          }
+        }
+      }
+
       /// This class is used to transition when the nav expands/collapses on
       /// larger screen sizes
       .rmd-layout-h {

package/src/layout/layoutNavStyles.ts

@@ -4,7 +4,7 @@ import { bem } from "../utils/bem.js";
 const styles = bem("rmd-layout-nav");
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutNavClassNameOptions {
   className?: string;
@@ -18,7 +18,7 @@ export interface LayoutNavClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function layoutNav(options: LayoutNavClassNameOptions = {}): string {
   const { className, appBarOffset } = options;

package/src/layout/layoutWindowSplitterStyles.ts

@@ -4,7 +4,7 @@ import { bem } from "../utils/bem.js";
 const styles = bem("rmd-layout-splitter");
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutWindowSplitterClassNameOptions {
   className?: string;
@@ -28,7 +28,7 @@ export interface LayoutWindowSplitterClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function layoutWindowSplitter(
   options: LayoutWindowSplitterClassNameOptions = {}

package/src/layout/mainStyles.ts

@@ -4,7 +4,7 @@ import { bem } from "../utils/bem.js";
 const styles = bem("rmd-layout-main");
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface MainClassNameOptions {
   className?: string;
@@ -29,7 +29,7 @@ export interface MainClassNameOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function main(options: MainClassNameOptions = {}): string {
   const { navOffset, appBarOffset, className } = options;

package/src/layout/useExpandableLayout.ts

@@ -1,23 +1,28 @@
 "use client";
+import { cnb } from "cnbuilder";
 import { useAppSize } from "../media-queries/AppSizeProvider.js";
-import type { CSSTransitionElementProps } from "../transition/types.js";
-import type { CssPosition, UseStateInitializer } from "../types.js";
+import { type CSSTransitionElementProps } from "../transition/types.js";
+import { type CssPosition, type UseStateInitializer } from "../types.js";
 import { useToggle } from "../useToggle.js";
-import type { LayoutNavProps } from "./LayoutNav.js";
-import type { HorizontalLayoutTransitionOptions } from "./useHorizontalLayoutTransition.js";
-import { useHorizontalLayoutTransition } from "./useHorizontalLayoutTransition.js";
+import { type LayoutNavProps } from "./LayoutNav.js";
+import {
+  useHorizontalLayoutTransition,
+  type HorizontalLayoutTransitionOptions,
+} from "./useHorizontalLayoutTransition.js";
+import { useSsr } from "../SsrProvider.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import type { useResizableLayout } from "./useResizableLayout.js";
-import type {
-  ProvidedTemporaryLayoutAppBarProps,
-  ProvidedTemporaryLayoutMainProps,
-  TemporaryLayoutImplementation,
-  TemporaryLayoutOptions,
+import { type useResizableLayout } from "./useResizableLayout.js";
+import {
+  useTemporaryLayout,
+  type ProvidedLayoutNavToggleProps,
+  type ProvidedTemporaryLayoutAppBarProps,
+  type ProvidedTemporaryLayoutMainProps,
+  type TemporaryLayoutImplementation,
+  type TemporaryLayoutOptions,
 } from "./useTemporaryLayout.js";
-import { useTemporaryLayout } from "./useTemporaryLayout.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ExpandableLayoutOptions extends TemporaryLayoutOptions {
   /** @defaultValue `"fixed"` */
@@ -32,9 +37,13 @@ export interface ExpandableLayoutOptions extends TemporaryLayoutOptions {
    * by the navigation. The default behavior is to place the navigation below
    * the fixed header.
    *
+   * Set this to `"static"` to make the navigation span the full height of the
+   * screen and hide the button until the screen shrinks to the temporary
+   * layout type.
+   *
    * @defaultValue `false`
    */
-  fullHeightNav?: boolean;
+  fullHeightNav?: boolean | "static";
 
   /** @see {@link HorizontalLayoutTransitionOptions} */
   transitionProps?: Omit<HorizontalLayoutTransitionOptions, "transitionIn">;
@@ -49,14 +58,14 @@ export interface ExpandableLayoutOptions extends TemporaryLayoutOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ProvidedLayoutMainProps
   extends ProvidedTemporaryLayoutMainProps,
     CSSTransitionElementProps<HTMLElement> {}
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedLayoutNavProps = Pick<
   LayoutNavProps,
@@ -64,29 +73,38 @@ export type ProvidedLayoutNavProps = Pick<
 >;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProvidedLayoutAppBarProps = ProvidedTemporaryLayoutAppBarProps &
   Partial<CSSTransitionElementProps<HTMLElement>>;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
+ */
+export interface ProvidedExpandableLayoutNavToggleProps
+  extends ProvidedLayoutNavToggleProps {
+  className: string;
+}
+
+/**
+ * @since 6.0.0
  */
 export interface ExpandableLayoutImplementation
   extends TemporaryLayoutImplementation {
   temporary: boolean;
+  persistent: boolean;
   expanded: boolean;
   expandNavigation(): void;
   collapseNavigation(): void;
   toggleNavigation(): void;
   appBarProps: ProvidedLayoutAppBarProps;
   mainProps: ProvidedLayoutMainProps;
+  navToggleProps: ProvidedExpandableLayoutNavToggleProps;
   expandableNavProps: ProvidedLayoutNavProps;
 }
 
 /**
- * @example
- * Main USage
+ * @example Main Usage
  * ```tsx
  * import {
  *   AppBarTitle,
@@ -146,20 +164,62 @@ export interface ExpandableLayoutImplementation
  * }
  * ```
  *
- * @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 Safely Conditionally Rendering
+ * ```diff
+ *   const {
+ *     temporary,
+ * +   persistent,
+ *     appBarProps,
+ *     expandableNavProps,
+ *     mainProps,
+ *     navToggleProps,
+ *     temporaryNavProps,
+ *     windowSplitterProps,
+ *   } = useExpandableLayout({ pathname });
+ *
+ *   return {
+ *     <>
+ *       <LayoutAppBar {...appBarProps}>
+ *         <Button {...navToggleProps} />
+ *         <AppBarTitle>Hello, world!</AppBarTitle>
+ *       </LayoutAppBar>
+ * -     <LayoutNav {...expandableNavProps}>
+ * -       <CustomNavigation />
+ * -     </LayoutNav>
+ * +     {persistent && (
+ * +       <LayoutNav {...expandableNavProps}>
+ * +         <CustomNavigation />
+ * +       </LayoutNav>
+ * +     )}
+ *       {temporary && (
+ *         <Sheet {...temporaryNavProps}>
+ *           <CustomNavigation />
+ *         </Sheet>
+ *       )}
+ *       <Main {...mainProps}>{children}</Main>
+ *     </>
+ *   }
+ * ```
+ *
+ * @since 6.0.0
  * @see {@link useResizableLayout}
  */
 export function useExpandableLayout(
   options: ExpandableLayoutOptions
 ): ExpandableLayoutImplementation {
   const {
-    defaultExpanded = false,
     fullHeightNav = false,
-    transitionProps,
     temporaryUntil = "tablet",
+    transitionProps,
+    defaultExpanded = fullHeightNav === "static",
     ...temporaryOptions
   } = options;
 
+  const ssr = useSsr();
   const {
     appBarProps,
     mainProps,
@@ -186,6 +246,7 @@ export function useExpandableLayout(
   return {
     visible,
     temporary,
+    persistent: ssr || !temporary,
     hideTemporaryNav,
     showTemporaryNav,
     expanded,
@@ -214,6 +275,7 @@ export function useExpandableLayout(
           toggleNavigation();
         }
       },
+      className: cnb(fullHeightNav === "static" && "rmd-layout-nav-toggle"),
     },
   };
 }

package/src/layout/useHorizontalLayoutTransition.ts

@@ -1,16 +1,16 @@
 "use client";
 import { cnb } from "cnbuilder";
 import { DEFAULT_SHEET_TIMEOUT } from "../sheet/Sheet.js";
-import type {
-  CSSTransitionClassNames,
-  CSSTransitionHookReturnValue,
-  PreconfiguredCSSTransitionOptions,
-  TransitionTimeout,
+import {
+  type CSSTransitionClassNames,
+  type CSSTransitionHookReturnValue,
+  type PreconfiguredCSSTransitionOptions,
+  type TransitionTimeout,
 } from "../transition/types.js";
 import { useCSSTransition } from "../transition/useCSSTransition.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export const DEFAULT_HORIZONTAL_LAYOUT_TRANSITION_CLASSNAMES = {
   appearDone: "rmd-layout-h--active",
@@ -21,7 +21,7 @@ export const DEFAULT_HORIZONTAL_LAYOUT_TRANSITION_CLASSNAMES = {
 } satisfies Readonly<CSSTransitionClassNames>;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HorizontalLayoutTransitionOptions
   extends PreconfiguredCSSTransitionOptions<HTMLElement> {
@@ -74,7 +74,7 @@ export interface HorizontalLayoutTransitionOptions
  * }
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useHorizontalLayoutTransition<
   E extends HTMLElement = HTMLElement,

package/src/layout/useLayoutAppBarHeight.ts

@@ -1,8 +1,7 @@
 "use client";
-import type { Ref, RefCallback } from "react";
-import { useMemo } from "react";
-import type { DefinedCSSVariableName } from "../theme/types.js";
-import type { CSSVariable } from "../theme/useCSSVariables.js";
+import { useMemo, type Ref, type RefCallback } from "react";
+import { type DefinedCSSVariableName } from "../theme/types.js";
+import { type CSSVariable } from "../theme/useCSSVariables.js";
 import { useElementSize } from "../useElementSize.js";
 
 declare module "react" {
@@ -13,7 +12,7 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface LayoutAppBarHeightResult {
   height: number | undefined;
@@ -22,8 +21,7 @@ export interface LayoutAppBarHeightResult {
 }
 
 /**
- * @example
- * Main Usage
+ * @example Main Usage
  * ```tsx
  * import type { PropsWithChildren, ReactElement } from "react";
  * import {
@@ -44,8 +42,7 @@ export interface LayoutAppBarHeightResult {
  * };
  * ```
  *
- * @example
- * Inline Variables
+ * @example Inline Variables
  * ```tsx
  * import type { PropsWithChildren, ReactElement } from "react";
  * import {
@@ -69,22 +66,22 @@ export interface LayoutAppBarHeightResult {
  * };
  * ```
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function useLayoutAppBarHeight(
   ref?: Ref<HTMLDivElement>
 ): LayoutAppBarHeightResult {
-  const { height, elementRef } = useElementSize({
+  const { height, elementRef, observedOnce } = useElementSize({
     ref,
     disableWidth: true,
   });
   const variables = useMemo<CSSVariable<DefinedCSSVariableName>[]>(() => {
-    if (Number.isNaN(height)) {
+    if (Number.isNaN(height) || !observedOnce) {
       return [];
     }
 
     return [{ name: "--rmd-layout-header-height", value: `${height}px` }];
-  }, [height]);
+  }, [height, observedOnce]);
 
   return {
     height,

package/src/layout/useLayoutTree.ts

@@ -1,13 +1,13 @@
 "use client";
 import { useEffect, useMemo } from "react";
-import type { TreeProps } from "../tree/Tree.js";
-import type {
-  DefaultTreeItemNode,
-  TreeData,
-  TreeItemDefaultIds,
-  TreeItemNode,
+import { type TreeProps } from "../tree/Tree.js";
+import {
+  type DefaultTreeItemNode,
+  type TreeData,
+  type TreeItemDefaultIds,
+  type TreeItemNode,
 } from "../tree/types.js";
-import type { TreeImplementation } from "../tree/useTree.js";
+import { type TreeImplementation } from "../tree/useTree.js";
 import { useTreeExpansion } from "../tree/useTreeExpansion.js";
 import { getTreeItemsFrom } from "../tree/utils.js";
 
@@ -25,7 +25,7 @@ const getParentIds = (
   getTreeItemsFrom(navItems, itemId).map(({ itemId }) => itemId);
 
 /**
- * @remarks \@since 6.0.0 Removed the `linkComponent` option.
+ * @since 6.0.0 Removed the `linkComponent` option.
  */
 export interface LayoutTreeOptions<
   T extends TreeItemNode = DefaultTreeItemNode,
@@ -79,7 +79,7 @@ export interface LayoutTreeOptions<
 }
 
 /**
- * @remarks \@since 6.0.0 Renamed from `LayoutNavigationState`, removed the
+ * @since 6.0.0 Renamed from `LayoutNavigationState`, removed the
  * `linkComponent`, and remap `navItems` to `data` so it can be passed to the
  * `Tree` component.
  */
@@ -165,7 +165,7 @@ export interface LayoutTreeImplementation<
  * }
  * ```
  *
- * @remarks \@since 6.0.0 Renamed from `useLayoutNavigation`.
+ * @since 6.0.0 Renamed from `useLayoutNavigation`.
  */
 export function useLayoutTree(
   options: LayoutTreeOptions