feat(side-panel): add useSidePanelState hook, animation zhoosh (#4230)

nkrantz · web-flow · commit 3e9bf5fbdbfa · 2025-02-11T15:13:21.000-05:00
diff --git a/.changeset/itchy-teachers-dance.md b/.changeset/itchy-teachers-dance.md
@@ -0,0 +1,6 @@
+---
+"@twilio-paste/side-panel": minor
+"@twilio-paste/core": minor
+---
+
+[Side Panel] Update mobile styles, add useSidePanelState hook, animation fixes
diff --git a/.changeset/lazy-months-roll.md b/.changeset/lazy-months-roll.md
@@ -0,0 +1,5 @@
+---
+"@twilio-paste/codemods": minor
+---
+
+[Codemods] new export from Side Panel: useSidePanelState()
diff --git a/packages/paste-codemods/tools/.cache/mappings.json b/packages/paste-codemods/tools/.cache/mappings.json
@@ -263,6 +263,7 @@
   "SidePanelHeader": "@twilio-paste/core/side-panel",
   "SidePanelHeaderActions": "@twilio-paste/core/side-panel",
   "SidePanelPushContentWrapper": "@twilio-paste/core/side-panel",
+  "useSidePanelState": "@twilio-paste/core/side-panel",
   "Sidebar": "@twilio-paste/core/sidebar",
   "SidebarBetaBadge": "@twilio-paste/core/sidebar",
   "SidebarBody": "@twilio-paste/core/sidebar",
diff --git a/packages/paste-core/components/side-panel/package.json b/packages/paste-core/components/side-panel/package.json
@@ -34,6 +34,7 @@
     "@twilio-paste/customization": "^8.1.1",
     "@twilio-paste/design-tokens": "^10.3.0",
     "@twilio-paste/icons": "^12.4.0",
+    "@twilio-paste/modal-dialog-primitive": "^2.0.1",
     "@twilio-paste/spinner": "^14.1.2",
     "@twilio-paste/stack": "^8.1.0",
     "@twilio-paste/style-props": "^9.1.1",
@@ -57,6 +58,7 @@
     "@twilio-paste/customization": "^8.1.1",
     "@twilio-paste/design-tokens": "^10.7.0",
     "@twilio-paste/icons": "^12.7.0",
+    "@twilio-paste/modal-dialog-primitive": "^2.0.1",
     "@twilio-paste/spinner": "^14.1.2",
     "@twilio-paste/stack": "^8.1.0",
     "@twilio-paste/style-props": "^9.1.1",
diff --git a/packages/paste-core/components/side-panel/src/SidePanel.tsx b/packages/paste-core/components/side-panel/src/SidePanel.tsx
@@ -1,12 +1,41 @@
 import { animated, useTransition } from "@twilio-paste/animation-library";
-import { Box, safelySpreadBoxProps } from "@twilio-paste/box";
+import { Box, getCustomElementStyles, safelySpreadBoxProps } from "@twilio-paste/box";
 import type { BoxProps } from "@twilio-paste/box";
+import { ModalDialogPrimitiveContent, ModalDialogPrimitiveOverlay } from "@twilio-paste/modal-dialog-primitive";
+import { css, styled } from "@twilio-paste/styling-library";
+import { pasteBaseStyles, useTheme } from "@twilio-paste/theme";
 import { useMergeRefs, useWindowSize } from "@twilio-paste/utils";
 import * as React from "react";
 
 import { SidePanelContext } from "./SidePanelContext";
 import type { SidePanelProps } from "./types";
 
+const SidePanelMobileOverlay = animated(
+  // @ts-expect-error the styled div color prop from emotion is clashing with our color style prop in BoxProps
+  styled(ModalDialogPrimitiveOverlay)(
+    css({
+      backgroundColor: "colorBackgroundOverlay",
+      position: "fixed",
+      top: 0,
+      right: 0,
+      bottom: 0,
+      left: 0,
+      width: "100%",
+      zIndex: "zIndex80",
+    }),
+    /*
+     * import Paste Theme Based Styles due to portal positioning.
+     * reach portal is a sibling to the main app, so you are now
+     * no longer a child of the theme provider. We need to re-set
+     * some of the base styles that we rely on inheriting from
+     * such as font-family and line-height so that compositions
+     * of paste components in the side panel are styled correctly.
+     */
+    pasteBaseStyles,
+    getCustomElementStyles,
+  ),
+);
+
 const StyledSidePanelWrapper = React.forwardRef<HTMLDivElement, BoxProps>((props, ref) => (
   <Box
     {...props}
@@ -19,6 +48,7 @@ const StyledSidePanelWrapper = React.forwardRef<HTMLDivElement, BoxProps>((props
     paddingRight={["space0", "space40", "space40"]}
     width={["100%", "size40", "size40"]}
     height={props.height}
+    boxSizing="content-box"
   />
 ));
 
@@ -31,87 +61,148 @@ const config = {
   friction: 20,
 };
 
-const transitionStyles = {
-  from: { opacity: 0, transform: "translateX(100%)" },
-  enter: { opacity: 1, transform: "translateX(0%)" },
-  leave: { opacity: 0, transform: "translateX(100%)" },
-  config,
-};
-
-const mobileTransitionStyles = {
-  from: { opacity: 0, transform: "translateY(100%)" },
-  enter: { opacity: 1, transform: "translateY(0%)" },
-  leave: { opacity: 0, transform: "translateY(100%)" },
-  config,
-};
-
-const SidePanel = React.forwardRef<HTMLDivElement, SidePanelProps>(
-  ({ element = "SIDE_PANEL", label, children, ...props }, ref) => {
-    const { sidePanelId, isOpen } = React.useContext(SidePanelContext);
-
-    const { breakpointIndex } = useWindowSize();
-
-    const transitions =
-      breakpointIndex === 0 ? useTransition(isOpen, mobileTransitionStyles) : useTransition(isOpen, transitionStyles);
-
-    const screenSize = window.innerHeight;
+interface SidePanelContentsProps extends SidePanelProps {
+  sidePanelId: string;
+  styles: any;
+  isMobile: boolean;
+}
 
+const SidePanelContents = React.forwardRef<HTMLDivElement, SidePanelContentsProps>(
+  ({ label, element, sidePanelId, styles, isMobile, children, ...props }, ref) => {
+    // Get the offset of the side panel from the top of the viewport
     const sidePanelRef = React.useRef<HTMLDivElement>(null);
     const mergedSidePanelRef = useMergeRefs(sidePanelRef, ref) as React.RefObject<HTMLDivElement>;
-
+    const screenSize = window.innerHeight;
     const [offsetY, setOffsetY] = React.useState(0);
-
-    // Get the offset of the side panel from the top of the viewport
     React.useEffect(() => {
       const boundingClientRect = sidePanelRef?.current?.getBoundingClientRect();
       setOffsetY(boundingClientRect?.y || 0);
     }, []);
 
+    return (
+      <Box
+        {...safelySpreadBoxProps(props)}
+        position="absolute"
+        role="dialog"
+        as={isMobile ? (ModalDialogPrimitiveContent as any) : "div"}
+        aria-label={label}
+        top={0}
+        right={0}
+        width={["100%", "auto", "auto"]}
+        height="100%"
+        element={element}
+        id={sidePanelId}
+      >
+        <AnimatedStyledSidePanelWrapper
+          ref={mergedSidePanelRef}
+          element={`ANIMATED_${element}_WRAPPER`}
+          style={styles}
+          height={["100%", screenSize - offsetY, screenSize - offsetY]}
+          top={[0, offsetY, offsetY]}
+          position="relative"
+          overflow="hidden"
+        >
+          <Box
+            display="flex"
+            flexDirection="column"
+            width={["100%", "388px", "388px"]} // 400px - 12px
+            position="absolute"
+            top={0}
+            left={[0, 12, 12]}
+            bottom={0}
+            borderStyle="solid"
+            borderBottomLeftRadius={["borderRadius0", "borderRadius70", "borderRadius70"]}
+            borderBottomRightRadius={["borderRadius0", "borderRadius70", "borderRadius70"]}
+            borderTopRightRadius={["borderRadius60", "borderRadius70", "borderRadius70"]}
+            borderTopLeftRadius={["borderRadius60", "borderRadius70", "borderRadius70"]}
+            borderWidth="borderWidth10"
+            borderColor="colorBorderWeaker"
+            backgroundColor="colorBackgroundBody"
+            marginTop={["space100", "space40", "space40"]}
+            marginBottom={["space0", "space40", "space40"]}
+            paddingBottom="space70"
+            element={`INNER_${element}`}
+          >
+            {children}
+          </Box>
+        </AnimatedStyledSidePanelWrapper>
+      </Box>
+    );
+  },
+);
+SidePanelContents.displayName = "SidePanelContents";
+
+const SidePanel = React.forwardRef<HTMLDivElement, SidePanelProps>(
+  ({ element = "SIDE_PANEL", label, children, ...props }, ref) => {
+    const theme = useTheme();
+    const { sidePanelId, isOpen } = React.useContext(SidePanelContext);
+    // Determine whether this is the initial render in order to block enter animations
+    const [isFirstRender, setIsFirstRender] = React.useState(true);
+    React.useEffect(() => {
+      if (isFirstRender) {
+        setIsFirstRender(false);
+      }
+    }, [isFirstRender]);
+
+    // Define transition styles for both breakpoints
+    const transitionStyles = {
+      from: isFirstRender ? undefined : { opacity: 0, width: "0px" },
+      enter: { opacity: 1, width: "400px" },
+      leave: { opacity: 0, width: "0px" },
+      config,
+    };
+    const mobileTransitionStyles = {
+      from: isFirstRender ? undefined : { opacity: 0, transform: "translateY(100%)" },
+      enter: { opacity: 1, transform: "translateY(0%)" },
+      leave: { opacity: 0, transform: "translateY(100%)" },
+      config,
+    };
+
+    // Set mobile or desktop transitions based on breakpointIndex
+    const { breakpointIndex } = useWindowSize();
+    const desktopTransitions = useTransition(isOpen, transitionStyles);
+    const mobileTransitions = useTransition(isOpen, mobileTransitionStyles);
+    const transitions = React.useMemo(() => {
+      if (breakpointIndex === 0) return mobileTransitions;
+      return desktopTransitions;
+    }, [breakpointIndex, desktopTransitions, mobileTransitions]);
+
     return (
       <>
         {transitions(
           (styles, item) =>
-            item && (
-              <Box
-                {...safelySpreadBoxProps(props)} // moved this from animated wrapper... might cause something
-                position="absolute"
-                role="dialog"
-                aria-label={label}
-                top={0}
-                right={0}
-                width={["100%", "auto", "auto"]}
-                height="100%"
-                element={element}
-                id={sidePanelId}
+            item &&
+            (breakpointIndex === 0 ? (
+              <SidePanelMobileOverlay
+                theme={theme}
+                data-paste-element={`${element}_OVERLAY`}
+                style={{ opacity: styles.opacity }}
               >
-                <AnimatedStyledSidePanelWrapper
-                  ref={mergedSidePanelRef}
-                  element={`ANIMATED_${element}_WRAPPER`}
-                  style={styles}
-                  height={screenSize - offsetY}
-                  top={offsetY}
+                <SidePanelContents
+                  {...props}
+                  element={element}
+                  sidePanelId={sidePanelId}
+                  styles={styles}
+                  label={label}
+                  isMobile
+                  ref={ref}
                 >
-                  <Box
-                    display="flex"
-                    maxHeight="100%"
-                    flexDirection="column"
-                    width={["100%", "size40", "size40"]}
-                    borderStyle="solid"
-                    borderRadius={["borderRadius0", "borderRadius70", "borderRadius70"]}
-                    borderWidth="borderWidth10"
-                    borderColor="colorBorderWeaker"
-                    backgroundColor="colorBackgroundBody"
-                    marginTop="space40"
-                    marginBottom={["space0", "space40", "space40"]}
-                    paddingBottom="space70"
-                    overflowY="hidden"
-                    element={`INNER_${element}`}
-                  >
-                    {children}
-                  </Box>
-                </AnimatedStyledSidePanelWrapper>
-              </Box>
-            ),
+                  {children}
+                </SidePanelContents>
+              </SidePanelMobileOverlay>
+            ) : (
+              <SidePanelContents
+                {...props}
+                element={element}
+                sidePanelId={sidePanelId}
+                styles={styles}
+                label={label}
+                isMobile={false}
+                ref={ref}
+              >
+                {children}
+              </SidePanelContents>
+            )),
         )}
       </>
     );
diff --git a/packages/paste-core/components/side-panel/src/SidePanelFooter.tsx b/packages/paste-core/components/side-panel/src/SidePanelFooter.tsx
@@ -11,7 +11,7 @@ const SidePanelFooter = React.forwardRef<HTMLDivElement, SidePanelFooterProps>(
         paddingX={variant === "chat" ? "space50" : "space70"}
         paddingBottom="space50"
         paddingTop={variant === "chat" ? "space0" : "space50"}
-        boxShadow={variant === "chat" ? "none" : "shadow"}
+        boxShadow={variant === "chat" ? "none" : "shadowElevationTop05"}
         marginBottom="spaceNegative70"
         zIndex="zIndex20"
         display="flex"
diff --git a/packages/paste-core/components/side-panel/src/SidePanelHeader.tsx b/packages/paste-core/components/side-panel/src/SidePanelHeader.tsx
@@ -4,15 +4,7 @@ import { CloseIcon } from "@twilio-paste/icons/esm/CloseIcon";
 import * as React from "react";
 
 import { SidePanelContext } from "./SidePanelContext";
-import type { SidePanelHeaderProps } from "./types";
-
-type SidePanelCloseButtonProps = {
-  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
-  i18nCloseSidePanelTitle: string;
-  sidePanelId: string;
-  isOpen: boolean;
-  element: string;
-};
+import type { SidePanelCloseButtonProps, SidePanelHeaderProps } from "./types";
 
 const SidePanelCloseButton: React.FC<React.PropsWithChildren<SidePanelCloseButtonProps>> = ({
   setIsOpen,
diff --git a/packages/paste-core/components/side-panel/src/SidePanelPushContentWrapper.tsx b/packages/paste-core/components/side-panel/src/SidePanelPushContentWrapper.tsx
@@ -34,7 +34,7 @@ export const SidePanelPushContentWrapper = React.forwardRef<HTMLDivElement, Side
         {...safelySpreadBoxProps(props)}
         ref={ref}
         // when using side panels in responsive layouts, we don't want any left margin in small screen, or initial SSR render situations. So basically never apply it in those situations
-        style={breakpointIndex === (undefined || 0) ? undefined : styles}
+        style={breakpointIndex === undefined || breakpointIndex === 0 ? undefined : styles}
         marginRight={["space0", theme.sizes.size40]}
         minWidth="size0"
         element={element}
diff --git a/packages/paste-core/components/side-panel/src/hooks.ts b/packages/paste-core/components/side-panel/src/hooks.ts
@@ -0,0 +1,12 @@
+import * as React from "react";
+
+import type { SidePanelStateReturn, UseSidePanelStateProps } from "./types";
+
+export const useSidePanelState = ({ open = false }: UseSidePanelStateProps = {}): SidePanelStateReturn => {
+  const [isOpen, setIsOpen] = React.useState(open);
+
+  return {
+    isOpen,
+    setIsOpen,
+  };
+};
diff --git a/packages/paste-core/components/side-panel/src/index.tsx b/packages/paste-core/components/side-panel/src/index.tsx
@@ -17,5 +17,7 @@ export type {
   SidePanelContainerProps,
   SidePanelBodyProps,
   SidePanelFooterProps,
+  SidePanelStateReturn,
 } from "./types";
 export { SidePanelContext } from "./SidePanelContext";
+export { useSidePanelState } from "./hooks";
diff --git a/packages/paste-core/components/side-panel/src/types.ts b/packages/paste-core/components/side-panel/src/types.ts
@@ -175,3 +175,33 @@ export interface SidePanelContextProps {
   i18nCloseSidePanelTitle: string;
   i18nOpenSidePanelTitle: string;
 }
+
+export interface SidePanelStateReturn {
+  /**
+   * State for the Side Panel. Determines whether the Side Panel is open or closed.
+   *
+   * @type {boolean}
+   * @default false
+   * @memberof SidePanelStateReturn
+   */
+  isOpen: boolean;
+  /**
+   * Sets the state of the Side Panel between open and closed.
+   *
+   * @type {React.Dispatch<React.SetStateAction<boolean>>}
+   * @memberof SidePanelStateReturn
+   */
+  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+}
+
+export interface UseSidePanelStateProps {
+  open?: boolean;
+}
+
+export type SidePanelCloseButtonProps = {
+  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+  i18nCloseSidePanelTitle: string;
+  sidePanelId: string;
+  isOpen: boolean;
+  element: string;
+};
diff --git a/packages/paste-core/components/side-panel/stories/index.stories.tsx b/packages/paste-core/components/side-panel/stories/index.stories.tsx
diff --git a/packages/paste-website/src/components/shortcodes/live-preview/index.tsx b/packages/paste-website/src/components/shortcodes/live-preview/index.tsx
diff --git a/packages/paste-website/src/pages/components/paragraph/api.mdx b/packages/paste-website/src/pages/components/paragraph/api.mdx
diff --git a/packages/paste-website/src/pages/components/side-panel/index.mdx b/packages/paste-website/src/pages/components/side-panel/index.mdx
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@twilio-paste/codemods": minor
 +---
++
 +[Codemods] new export from Side Panel: useSidePanelState()