@sproutsocial/seeds-react-panel 1.0.11 → 1.1.2

package/src/PanelFooter.tsx

@@ -1,11 +1,58 @@
 import * as React from "react";
+import { needsStyledComponents } from "@sproutsocial/seeds-react-system-props";
 import { Footer } from "./styles";
+import { cn } from "./PanelShared";
 import type { TypePanelFooterProps } from "./PanelTypes";
 
-export const PanelFooter = ({ children, ...rest }: TypePanelFooterProps) => (
+/**
+ * Styled-components footer — the backward-compatible fallback. Routed to when
+ * the consumer passes styled-system props (e.g. `<Panel.Footer bg="...">`).
+ */
+const PanelFooterStyled = ({ children, ...rest }: TypePanelFooterProps) => (
   <Footer p={450} data-panel-footer="" {...rest}>
     {children}
   </Footer>
 );
 
+/**
+ * Tailwind/CSS-class footer — the preferred path. Renders a plain
+ * `<div data-panel-footer>` with the `seeds-panel-footer` class from panel.css.
+ *
+ * `margin-bottom: var(--bleed, 0px)` lifts the footer above the Drawer's mobile
+ * bottom-sheet bleed (see styles.ts). It is asserted by the jsdom tests and the
+ * `--bleed` var is only set at runtime by the mobile Drawer, so it is applied
+ * inline (falling back to 0px on desktop).
+ */
+const PanelFooterTailwind = ({ children, ...rest }: TypePanelFooterProps) => {
+  const { className, style, ...domRest } = rest as {
+    className?: string;
+    style?: React.CSSProperties;
+  } & Record<string, unknown>;
+
+  return (
+    <div
+      className={cn("seeds-panel-footer", className)}
+      style={{ marginBottom: "var(--bleed, 0px)", ...style }}
+      data-panel-footer=""
+      {...domRest}
+    >
+      {children}
+    </div>
+  );
+};
+
+/**
+ * Hybrid footer router. Routes on the leftover props after the footer's own
+ * props are removed.
+ */
+export const PanelFooter = (props: TypePanelFooterProps) => {
+  const { children, ...rest } = props;
+
+  if (needsStyledComponents(rest)) {
+    return <PanelFooterStyled {...props} />;
+  }
+
+  return <PanelFooterTailwind {...props} />;
+};
+
 PanelFooter.displayName = "Panel.Footer";

package/src/PanelHeader.tsx

@@ -1,41 +1,90 @@
 import Box from "@sproutsocial/seeds-react-box";
 import Text from "@sproutsocial/seeds-react-text";
+import { needsStyledComponents } from "@sproutsocial/seeds-react-system-props";
 import { usePanelContext } from "./PanelContext";
 import { PanelCloseButton } from "./PanelCloseButton";
+import { cn } from "./PanelShared";
 import type { TypePanelHeaderProps } from "./PanelTypes";
 
-export const PanelHeader = ({
+/**
+ * Styled-components header — the backward-compatible fallback. The hybrid
+ * router sends consumers here whenever they pass styled-system props (e.g.
+ * `<Panel.Header alignItems="center">`) or a `styled()` extension, so the full
+ * `Box` prop surface keeps working.
+ */
+const PanelHeaderStyled = ({
   title = "",
   id = undefined,
   children,
   render,
   ...rest
-}: TypePanelHeaderProps) => {
-  const panelContext = usePanelContext();
+}: TypePanelHeaderProps) => (
+  <Box
+    display="flex"
+    flex="0 0 auto"
+    justifyContent="space-between"
+    alignItems="center"
+    p={400}
+    borderBottom="1px solid"
+    borderColor="container.border.base"
+    {...rest}
+  >
+    {children || (
+      <>
+        <Text.Headline id={id}>{title}</Text.Headline>
+        <PanelCloseButton />
+      </>
+    )}
+  </Box>
+);
 
-  if (render) {
-    return render(panelContext);
-  }
+/**
+ * Tailwind/CSS-class header — the preferred path. Renders a plain `<div>` with
+ * the `seeds-panel-header` class from panel.css instead of a styled `Box`. The
+ * `render` prop is handled by the hybrid before reaching here.
+ */
+const PanelHeaderTailwind = ({
+  title = "",
+  id = undefined,
+  children,
+  render,
+  ...rest
+}: TypePanelHeaderProps) => {
+  const { className, ...domRest } = rest as {
+    className?: string;
+  } & Record<string, unknown>;
 
   return (
-    <Box
-      display="flex"
-      flex="0 0 auto"
-      justifyContent="space-between"
-      alignItems="center"
-      p={400}
-      borderBottom="1px solid"
-      borderColor="container.border.base"
-      {...rest}
-    >
+    <div className={cn("seeds-panel-header", className)} {...domRest}>
       {children || (
         <>
           <Text.Headline id={id}>{title}</Text.Headline>
           <PanelCloseButton />
         </>
       )}
-    </Box>
+    </div>
   );
 };
 
+/**
+ * Hybrid header router. The `render` escape hatch short-circuits before any
+ * routing (matching the original always-styled behaviour); otherwise it routes
+ * on the leftover props after the header's own props are removed.
+ */
+export const PanelHeader = (props: TypePanelHeaderProps) => {
+  const panelContext = usePanelContext();
+
+  if (props.render) {
+    return props.render(panelContext);
+  }
+
+  const { title, id, children, render, ...rest } = props;
+
+  if (needsStyledComponents(rest)) {
+    return <PanelHeaderStyled {...props} />;
+  }
+
+  return <PanelHeaderTailwind {...props} />;
+};
+
 PanelHeader.displayName = "Panel.Header";

package/src/PanelHybrid.tsx

@@ -0,0 +1,52 @@
+import { needsStyledComponents } from "@sproutsocial/seeds-react-system-props";
+import { PanelStyled } from "./PanelStyled";
+import { PanelTailwind } from "./PanelTailwind";
+import type { TypePanelProps } from "./PanelTypes";
+
+/**
+ * Hybrid Panel router. Chooses the styled-components path when the consumer
+ * passes a styled-system (`COMMON`) prop or a `styled()` extension, otherwise
+ * the preferred Tailwind path.
+ *
+ * The routing decision runs on the *leftover* props after Panel's own domain
+ * props are destructured — critically, `width` and `zIndex` are Panel domain
+ * props whose names also appear in `STYLED_SYSTEM_PROPS`. Gating on the full
+ * prop object would push almost every real Panel usage (anything setting
+ * `width`) onto the styled path and defeat the migration, so we exclude the
+ * domain props first and gate only on `rest`.
+ */
+export const PanelHybrid = (props: TypePanelProps) => {
+  const {
+    children,
+    closeButtonLabel,
+    header,
+    headerless,
+    footer,
+    title,
+    titleId,
+    direction,
+    width,
+    gap,
+    mobileBreakpoint,
+    zIndex,
+    id,
+    snapPoints,
+    defaultSnapPoint,
+    snapPoint,
+    onSnapPointChange,
+    snapToSequentialPoints,
+    actions,
+    actionsInHeader,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+
+  if (needsStyledComponents(rest)) {
+    return <PanelStyled {...props} />;
+  }
+
+  return <PanelTailwind {...props} />;
+};
+
+PanelHybrid.displayName = "Panel";

package/src/PanelMobile.tsx

@@ -0,0 +1,90 @@
+import * as React from "react";
+import Drawer from "@sproutsocial/seeds-react-drawer";
+import { PanelContext } from "./PanelContext";
+import { PanelContent } from "./PanelContent";
+import { PanelMobileActionsHeader } from "./PanelMobileActionsHeader";
+import type { TypePanelShell } from "./PanelShared";
+
+/**
+ * Mobile bottom-sheet rendering, shared verbatim by both the styled and the
+ * Tailwind shells. The mobile path always renders through `Drawer`, which is
+ * itself already migrated to the hybrid pattern, so nothing here depends on the
+ * root routing gate — the two shells render an identical mobile tree.
+ */
+export const PanelMobile = ({ shell }: { shell: TypePanelShell }) => {
+  const {
+    rest,
+    children,
+    closeButtonLabel,
+    header,
+    headerless,
+    footer,
+    title,
+    titleId,
+    zIndex,
+    snapPoints,
+    defaultSnapPoint,
+    snapPoint,
+    onSnapPointChange,
+    snapToSequentialPoints,
+    actions,
+    actionsInHeader,
+    ariaLabel,
+    isPanelOpen,
+    closePanel,
+    enrichedValue,
+    effectiveAriaLabelledBy,
+  } = shell;
+
+  // With `actionsInHeader`, Drawer suppresses the floating rail and expects the
+  // consumer to render the actions inside a custom header. Auto-compose one
+  // (title + action pills + close pill) when the consumer hasn't supplied their
+  // own header; otherwise we'd drop `actions` on the floor.
+  const shouldRenderActionsHeader =
+    !headerless &&
+    header == null &&
+    actionsInHeader === true &&
+    !!actions &&
+    actions.length > 0;
+
+  // Headerless suppresses the built-in header entirely; the children own all
+  // chrome in that mode.
+  let defaultMobileHeader: React.ReactNode = null;
+  if (!headerless) {
+    defaultMobileHeader = shouldRenderActionsHeader ? (
+      <PanelMobileActionsHeader
+        title={title}
+        titleId={titleId}
+        actions={actions!}
+      />
+    ) : (
+      <Drawer.Header title={title} id={titleId} />
+    );
+  }
+
+  return (
+    <PanelContext.Provider value={enrichedValue}>
+      <Drawer
+        {...rest}
+        open={isPanelOpen}
+        onClose={closePanel}
+        direction="bottom"
+        closeButtonLabel={closeButtonLabel}
+        zIndex={zIndex}
+        snapPoints={snapPoints}
+        defaultSnapPoint={defaultSnapPoint}
+        snapPoint={snapPoint}
+        onSnapPointChange={onSnapPointChange}
+        snapToSequentialPoints={snapToSequentialPoints}
+        actions={actions}
+        actionsInHeader={actionsInHeader}
+        aria-labelledby={effectiveAriaLabelledBy}
+        aria-label={ariaLabel}
+      >
+        {header ?? defaultMobileHeader}
+        <PanelContent>{children}</PanelContent>
+        {footer}
+      </Drawer>
+    </PanelContext.Provider>
+  );
+};

package/src/PanelMobileActionsHeader.tsx

@@ -1,5 +1,4 @@
 import * as React from "react";
-import Box from "@sproutsocial/seeds-react-box";
 import Button from "@sproutsocial/seeds-react-button";
 import Drawer from "@sproutsocial/seeds-react-drawer";
 import Icon from "@sproutsocial/seeds-react-icon";
@@ -20,6 +19,10 @@ interface TypePanelMobileActionsHeaderProps {
  * pattern in `seeds-react-peek-in/PeekIn.tsx`. The Drawer's floating rail is
  * suppressed in this combination (`actionsInHeader` opts out), so without this
  * header the actions would render nowhere.
+ *
+ * This header is composed internally by Panel (it receives no consumer
+ * styled-system props), so its chrome is emitted directly as `seeds-panel-*`
+ * classes from panel.css rather than through a styled `Box`.
  */
 export const PanelMobileActionsHeader = ({
   title,
@@ -28,14 +31,7 @@ export const PanelMobileActionsHeader = ({
 }: TypePanelMobileActionsHeaderProps) => (
   <Drawer.Header
     render={(ctx) => (
-      <Box
-        display="flex"
-        alignItems="center"
-        justifyContent="space-between"
-        pt={400}
-        px={450}
-        flex="0 0 auto"
-      >
+      <div className="seeds-panel-mobile-actions-header">
         <Text
           as="h2"
           fontSize={400}
@@ -45,7 +41,7 @@ export const PanelMobileActionsHeader = ({
         >
           {title}
         </Text>
-        <Box display="flex" alignItems="center" gap={200}>
+        <div className="seeds-panel-mobile-actions-buttons">
           {actions.map((action, i) => (
             <Button
               key={i}
@@ -64,8 +60,8 @@ export const PanelMobileActionsHeader = ({
           >
             <Icon aria-hidden name="x-outline" />
           </Button>
-        </Box>
-      </Box>
+        </div>
+      </div>
     )}
   />
 );

package/src/PanelShared.tsx

@@ -0,0 +1,189 @@
+import * as React from "react";
+import { useIsMobile } from "@sproutsocial/seeds-react-hooks";
+import { usePanelContext } from "./PanelContext";
+import type {
+  PanelDirection,
+  TypePanelProps,
+  TypePanelContext,
+} from "./PanelTypes";
+
+/**
+ * Class-name merge helper. Copied intentionally rather than imported from
+ * `@sproutsocial/seeds-react-utilities` — `cn` is not exported there, so each
+ * migrated Tailwind component carries its own copy (mirrors AvatarTailwind /
+ * DrawerShared). Because Panel is a multi-part component, the helper lives once
+ * here and is imported by every Tailwind sub-component instead of being
+ * duplicated in each file.
+ */
+export function cn(
+  ...inputs: (string | undefined | null | false | Record<string, boolean>)[]
+): string {
+  const classes: string[] = [];
+
+  for (const input of inputs) {
+    if (!input) continue;
+
+    if (typeof input === "string") {
+      classes.push(input);
+    } else if (typeof input === "object") {
+      for (const [key, value] of Object.entries(input)) {
+        if (value) {
+          classes.push(key);
+        }
+      }
+    }
+  }
+
+  return classes.join(" ");
+}
+
+/**
+ * Dynamic geometry for the outer `<aside>` on the Tailwind path. These values
+ * depend on runtime props (open state, width, gap, direction) and are asserted
+ * as computed styles by the jsdom tests, so they must be inline `style` rather
+ * than CSS-variable-driven classes (panel.css is not loaded under jsdom). The
+ * static chrome (background, radius, transition, overflow, flex-grow/shrink)
+ * lives in panel.css.
+ *
+ * The gap sits on the margin edge facing the adjacent content: left when the
+ * panel anchors right, right when it anchors left, top when it anchors to the
+ * bottom (mirrors `gapSide` in styles.ts).
+ */
+export const getPanelContainerStyle = (
+  direction: PanelDirection,
+  width: number,
+  gap: number,
+  isPanelOpen: boolean
+): React.CSSProperties => {
+  const gapValue = isPanelOpen && gap ? `${gap}px` : "0px";
+  const style: React.CSSProperties = {
+    flexBasis: isPanelOpen ? `${width}px` : "0px",
+  };
+
+  if (direction === "bottom") {
+    style.width = "100%";
+  } else {
+    style.alignSelf = "stretch";
+  }
+
+  if (direction === "right") {
+    style.marginLeft = gapValue;
+  } else if (direction === "left") {
+    style.marginRight = gapValue;
+  } else {
+    style.marginTop = gapValue;
+  }
+
+  return style;
+};
+
+/**
+ * Dynamic geometry for the inner layout `<div>` on the Tailwind path. The
+ * direction-dependent min-width/min-height come from the `width` prop.
+ */
+export const getPanelInnerStyle = (
+  direction: PanelDirection,
+  width: number
+): React.CSSProperties =>
+  direction === "bottom"
+    ? { minHeight: `${width}px`, width: "100%" }
+    : { minWidth: `${width}px`, height: "100%" };
+
+/**
+ * Shared render logic for both the styled and the Tailwind shells: reads the
+ * PanelProvider context, enriches it (closeButtonLabel/headerless), freezes the
+ * last-rendered children during the collapse, resolves the mobile breakpoint,
+ * and computes the auto-wired accessible name. Centralising it here guarantees
+ * the two shells stay behaviourally identical — only the desktop container
+ * markup differs between them.
+ */
+export const usePanelShell = (props: TypePanelProps) => {
+  const {
+    children,
+    closeButtonLabel,
+    header,
+    headerless = false,
+    footer,
+    title,
+    titleId,
+    direction = "right",
+    width = 384,
+    gap = 4,
+    mobileBreakpoint,
+    zIndex,
+    id,
+    snapPoints,
+    defaultSnapPoint,
+    snapPoint,
+    onSnapPointChange,
+    snapToSequentialPoints,
+    actions,
+    actionsInHeader,
+    "aria-labelledby": ariaLabelledByProp,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+
+  const panelContext = usePanelContext();
+  const { isPanelOpen, closePanel } = panelContext;
+  const isMobile = useIsMobile(mobileBreakpoint);
+
+  // Expose closeButtonLabel through context so PanelCloseButton can read it
+  // without prop drilling — same pattern as DrawerContext.
+  const enrichedValue = React.useMemo<TypePanelContext>(
+    () => ({ ...panelContext, closeButtonLabel, headerless }),
+    [panelContext, closeButtonLabel, headerless]
+  );
+
+  // Freeze the last-rendered children during the collapse so consumers that
+  // conditionally render content don't produce an empty panel shell while the
+  // flex-basis animation runs.
+  const prevChildrenRef = React.useRef<React.ReactNode>(null);
+  if (isPanelOpen) {
+    prevChildrenRef.current = children;
+  }
+  const renderedChildren = isPanelOpen ? children : prevChildrenRef.current;
+
+  // When the consumer relies on the default header, its title element renders
+  // with `id={titleId}`. Auto-wire `aria-labelledby` so the dialog/aside has an
+  // accessible name without forcing every caller to repeat the id.
+  const effectiveAriaLabelledBy =
+    ariaLabelledByProp ?? (!headerless && header == null ? titleId : undefined);
+
+  return {
+    rest,
+    children,
+    closeButtonLabel,
+    header,
+    headerless,
+    footer,
+    title,
+    titleId,
+    direction,
+    width,
+    gap,
+    zIndex,
+    id,
+    snapPoints,
+    defaultSnapPoint,
+    snapPoint,
+    onSnapPointChange,
+    snapToSequentialPoints,
+    actions,
+    actionsInHeader,
+    ariaLabel,
+    isPanelOpen,
+    closePanel,
+    isMobile,
+    enrichedValue,
+    renderedChildren,
+    effectiveAriaLabelledBy,
+  };
+};
+
+/**
+ * The shared shell values consumed by both the styled and the Tailwind desktop
+ * shells and by the shared mobile render. Inferred from `usePanelShell` so the
+ * `rest` pass-through keeps its precise type (mirrors `TypeDrawerShell`).
+ */
+export type TypePanelShell = ReturnType<typeof usePanelShell>;

package/src/PanelStyled.tsx

@@ -0,0 +1,62 @@
+import { PanelContext } from "./PanelContext";
+import { PanelHeader } from "./PanelHeader";
+import { PanelContent } from "./PanelContent";
+import { PanelMobile } from "./PanelMobile";
+import { PanelContainer, PanelInner } from "./styles";
+import { usePanelShell } from "./PanelShared";
+import type { TypePanelProps } from "./PanelTypes";
+
+/**
+ * Styled-components shell — the backward-compatible fallback. The hybrid router
+ * sends consumers here whenever they pass a `COMMON`-mixin styled-system prop
+ * (e.g. `mt`, `mb`, `mr`) or a `styled()` extension, so the full styled prop
+ * surface on the outer container keeps working exactly as before.
+ */
+export const PanelStyled = (props: TypePanelProps) => {
+  const shell = usePanelShell(props);
+  const {
+    rest,
+    header,
+    headerless,
+    footer,
+    title,
+    titleId,
+    direction,
+    width,
+    gap,
+    id,
+    ariaLabel,
+    isPanelOpen,
+    isMobile,
+    enrichedValue,
+    renderedChildren,
+    effectiveAriaLabelledBy,
+  } = shell;
+
+  if (isMobile) {
+    return <PanelMobile shell={shell} />;
+  }
+
+  return (
+    <PanelContext.Provider value={enrichedValue}>
+      <PanelContainer
+        {...rest}
+        $isOpen={isPanelOpen}
+        $direction={direction}
+        $width={width}
+        $gap={gap}
+        data-qa-panel={id}
+        data-qa-panel-isopen={isPanelOpen}
+        aria-labelledby={effectiveAriaLabelledBy}
+        aria-label={ariaLabel}
+      >
+        <PanelInner $direction={direction} $width={width}>
+          {header ??
+            (headerless ? null : <PanelHeader title={title} id={titleId} />)}
+          <PanelContent>{renderedChildren}</PanelContent>
+          {footer}
+        </PanelInner>
+      </PanelContainer>
+    </PanelContext.Provider>
+  );
+};

package/src/PanelTailwind.tsx

@@ -0,0 +1,86 @@
+import * as React from "react";
+import { PanelContext } from "./PanelContext";
+import { PanelHeader } from "./PanelHeader";
+import { PanelContent } from "./PanelContent";
+import { PanelMobile } from "./PanelMobile";
+import {
+  cn,
+  usePanelShell,
+  getPanelContainerStyle,
+  getPanelInnerStyle,
+} from "./PanelShared";
+import type { TypePanelProps } from "./PanelTypes";
+
+/**
+ * Tailwind/CSS-class shell — the preferred path, routed to by the hybrid when
+ * the consumer passes no styled-system props or `styled()` extension. Renders a
+ * plain `<aside>` (implicit `complementary` role) with the `seeds-panel` classes
+ * from panel.css instead of a styled container. Runtime geometry (flex-basis,
+ * gap margin, direction shape, inner min-width/min-height) is applied inline
+ * because the jsdom tests assert those as computed styles and panel.css is not
+ * loaded there. The mobile path renders identically to the styled shell via
+ * the shared `PanelMobile`.
+ */
+export const PanelTailwind = (props: TypePanelProps) => {
+  const shell = usePanelShell(props);
+  const {
+    rest,
+    header,
+    headerless,
+    footer,
+    title,
+    titleId,
+    direction,
+    width,
+    gap,
+    id,
+    ariaLabel,
+    isPanelOpen,
+    isMobile,
+    enrichedValue,
+    renderedChildren,
+    effectiveAriaLabelledBy,
+  } = shell;
+
+  if (isMobile) {
+    return <PanelMobile shell={shell} />;
+  }
+
+  // `rest` carries only non-styled pass-through props on this path (the gate
+  // routes styled-system props to PanelStyled). Peel off className/style so we
+  // can merge them onto the component's own class and inline geometry rather
+  // than letting a spread clobber them.
+  const { className, style, ...domRest } = rest as {
+    className?: string;
+    style?: React.CSSProperties;
+  } & Record<string, unknown>;
+
+  const containerStyle = getPanelContainerStyle(
+    direction,
+    width,
+    gap,
+    isPanelOpen
+  );
+  const innerStyle = getPanelInnerStyle(direction, width);
+
+  return (
+    <PanelContext.Provider value={enrichedValue}>
+      <aside
+        {...domRest}
+        className={cn("seeds-panel", className)}
+        style={{ ...containerStyle, ...style }}
+        data-qa-panel={id}
+        data-qa-panel-isopen={isPanelOpen}
+        aria-labelledby={effectiveAriaLabelledBy}
+        aria-label={ariaLabel}
+      >
+        <div className="seeds-panel-inner" style={innerStyle}>
+          {header ??
+            (headerless ? null : <PanelHeader title={title} id={titleId} />)}
+          <PanelContent>{renderedChildren}</PanelContent>
+          {footer}
+        </div>
+      </aside>
+    </PanelContext.Provider>
+  );
+};