@sproutsocial/seeds-react-panel 0.3.7

package/src/Panel.stories.tsx

@@ -0,0 +1,376 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Box } from "@sproutsocial/seeds-react-box";
+import { Button } from "@sproutsocial/seeds-react-button";
+import { Text } from "@sproutsocial/seeds-react-text";
+import Panel, { PanelProvider, usePanelContext } from "./index";
+
+const ToggleButton = ({ label = "Toggle Panel" }: { label?: string }) => {
+  const { togglePanel } = usePanelContext();
+  return (
+    <Button appearance="primary" onClick={togglePanel}>
+      {label}
+    </Button>
+  );
+};
+
+const LayoutFrame = ({ children }: { children: React.ReactNode }) => (
+  <Box display="flex" height="100vh" width="100%" bg="neutral.900">
+    {children}
+  </Box>
+);
+
+const MainContentWrapper = ({ children }: { children: React.ReactNode }) => (
+  <Box flex="1 1 auto" overflow="auto" bg="neutral.100">
+    {children}
+  </Box>
+);
+
+const MainContent = () => (
+  <MainContentWrapper>
+    <Box p={500} mr={100}>
+      <Text.Headline as="h1">Main content</Text.Headline>
+      <Text.BodyCopy as="p">
+        The panel renders inline at desktop widths and pushes this content.
+        Below the mobile breakpoint, it switches to a bottom-sheet overlay.
+      </Text.BodyCopy>
+      <ToggleButton />
+    </Box>
+  </MainContentWrapper>
+);
+
+const PanelBody = () => (
+  <Panel.Content>
+    <Text.BodyCopy as="p">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam ac
+      consectetur tortor.
+    </Text.BodyCopy>
+  </Panel.Content>
+);
+
+const meta: Meta<typeof Panel> = {
+  title: "Components/Panel",
+  component: Panel,
+  parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof Panel>;
+
+export const Default: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const LeftSide: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <Panel
+          closeButtonLabel="Close"
+          direction="left"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <PanelBody />
+        </Panel>
+        <MainContent />
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const CustomWidth: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          width={500}
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const CustomHeader: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          header={
+            <Panel.Header>
+              <Text.Headline as="h2">Custom header</Text.Headline>
+              <Panel.CloseButton />
+            </Panel.Header>
+          }
+        >
+          <Panel.Content>
+            <Text.BodyCopy as="p">
+              When you supply a custom header via the header prop, you are
+              responsible for rendering Panel.CloseButton yourself.
+            </Text.BodyCopy>
+          </Panel.Content>
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const WithFooter: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <Panel.Content>
+            {Array.from({ length: 20 }, (_, i) => (
+              <Text.BodyCopy key={i} as="p">
+                Scrollable content line {i + 1}
+              </Text.BodyCopy>
+            ))}
+          </Panel.Content>
+          <Panel.Footer>
+            <Box display="flex" justifyContent="flex-end" gap={300}>
+              <Button appearance="secondary">Cancel</Button>
+              <Button appearance="primary">Save</Button>
+            </Box>
+          </Panel.Footer>
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const ClosedByDefault: Story = {
+  render: () => (
+    <PanelProvider>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const MobileBottomSheet: Story = {
+  parameters: {
+    viewport: { defaultViewport: "mobile1" },
+  },
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const MobileWithFooter: Story = {
+  parameters: {
+    viewport: { defaultViewport: "mobile1" },
+  },
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+        >
+          <Panel.Content>
+            {Array.from({ length: 20 }, (_, i) => (
+              <Text.BodyCopy key={i} as="p">
+                Scrollable content line {i + 1}
+              </Text.BodyCopy>
+            ))}
+          </Panel.Content>
+          <Panel.Footer>
+            <Box display="flex" justifyContent="flex-end" gap={300}>
+              <Button appearance="secondary">Cancel</Button>
+              <Button appearance="primary">Save</Button>
+            </Box>
+          </Panel.Footer>
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const MobileWithActions: Story = {
+  parameters: {
+    viewport: { defaultViewport: "mobile1" },
+  },
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+          actions={[
+            {
+              "aria-label": "Expand",
+              iconName: "arrows-pointing-out-outline",
+            },
+            { "aria-label": "Share", iconName: "link-outline" },
+          ]}
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+/**
+ * Exception: use `actionsInHeader` only when the floating rail above the
+ * bottom sheet would collide with surrounding UI — for example, nested sheets
+ * or snap-point layouts where the fully-expanded sheet leaves no room above.
+ */
+export const MobileWithActionsInHeader: Story = {
+  parameters: {
+    viewport: { defaultViewport: "mobile1" },
+  },
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          title="Panel title"
+          titleId="panel-header"
+          aria-labelledby="panel-header"
+          actions={[
+            {
+              "aria-label": "Expand",
+              iconName: "arrows-pointing-out-outline",
+            },
+            { "aria-label": "Share", iconName: "link-outline" },
+          ]}
+          actionsInHeader
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+export const CustomHeaderAndFooter: Story = {
+  render: () => (
+    <PanelProvider defaultOpen>
+      <LayoutFrame>
+        <MainContent />
+        <Panel
+          closeButtonLabel="Close"
+          header={
+            <Panel.Header>
+              <Text.Headline as="h2">Custom header</Text.Headline>
+              <Panel.CloseButton />
+            </Panel.Header>
+          }
+        >
+          <Panel.Content>
+            {Array.from({ length: 20 }, (_, i) => (
+              <Text.BodyCopy key={i} as="p">
+                Scrollable content line {i + 1}
+              </Text.BodyCopy>
+            ))}
+          </Panel.Content>
+          <Panel.Footer>
+            <Box display="flex" justifyContent="flex-end" gap={300}>
+              <Button appearance="secondary">Cancel</Button>
+              <Button appearance="primary">Save</Button>
+            </Box>
+          </Panel.Footer>
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  ),
+};
+
+const ControlledDemo = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <PanelProvider open={open} onOpenChange={setOpen}>
+      <LayoutFrame>
+        <MainContentWrapper>
+          <Box p={500}>
+            <Text.Headline as="h1">Controlled panel</Text.Headline>
+            <Text.BodyCopy as="p">
+              Open state is managed externally via <code>open</code> and{" "}
+              <code>onOpenChange</code>.
+            </Text.BodyCopy>
+            <Box display="flex" gap={300} mt={400}>
+              <Button appearance="primary" onClick={() => setOpen(true)}>
+                Open
+              </Button>
+              <Button appearance="secondary" onClick={() => setOpen(false)}>
+                Close
+              </Button>
+            </Box>
+          </Box>
+        </MainContentWrapper>
+        <Panel
+          closeButtonLabel="Close"
+          title="Controlled panel"
+          titleId="controlled-panel-header"
+          aria-labelledby="controlled-panel-header"
+        >
+          <PanelBody />
+        </Panel>
+      </LayoutFrame>
+    </PanelProvider>
+  );
+};
+
+export const Controlled: Story = {
+  render: () => <ControlledDemo />,
+};

package/src/Panel.tsx

@@ -0,0 +1,139 @@
+import * as React from "react";
+import Drawer from "@sproutsocial/seeds-react-drawer";
+import { useIsMobile } from "@sproutsocial/seeds-react-hooks";
+import { usePanelContext, PanelContext } from "./PanelContext";
+import { PanelHeader } from "./PanelHeader";
+import { PanelContent } from "./PanelContent";
+import { PanelCloseButton } from "./PanelCloseButton";
+import { PanelFooter } from "./PanelFooter";
+import { PanelMobileActionsHeader } from "./PanelMobileActionsHeader";
+import { PanelContainer, PanelInner } from "./styles";
+import type { TypePanelProps, TypePanelContext } from "./PanelTypes";
+
+const PanelComponent = ({
+  children,
+  closeButtonLabel,
+  header,
+  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
+}: TypePanelProps) => {
+  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 }),
+    [panelContext, closeButtonLabel]
+  );
+
+  // 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 ?? (header == null ? titleId : undefined);
+
+  if (isMobile) {
+    // 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 =
+      header == null &&
+      actionsInHeader === true &&
+      !!actions &&
+      actions.length > 0;
+
+    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 ??
+            (shouldRenderActionsHeader ? (
+              <PanelMobileActionsHeader
+                title={title}
+                titleId={titleId}
+                actions={actions!}
+              />
+            ) : (
+              <Drawer.Header title={title} id={titleId} />
+            ))}
+          {children}
+          {footer}
+        </Drawer>
+      </PanelContext.Provider>
+    );
+  }
+
+  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 ?? <PanelHeader title={title} id={titleId} />}
+          {renderedChildren}
+          {footer}
+        </PanelInner>
+      </PanelContainer>
+    </PanelContext.Provider>
+  );
+};
+
+PanelComponent.Header = PanelHeader;
+PanelComponent.Content = PanelContent;
+PanelComponent.CloseButton = PanelCloseButton;
+PanelComponent.Footer = PanelFooter;
+
+export const Panel = PanelComponent;
+export default PanelComponent;

package/src/PanelCloseButton.tsx

@@ -0,0 +1,26 @@
+import * as React from "react";
+import Button from "@sproutsocial/seeds-react-button";
+import Icon from "@sproutsocial/seeds-react-icon";
+import { usePanelContext } from "./PanelContext";
+import type { TypePanelCloseButtonProps } from "./PanelTypes";
+
+export const PanelCloseButton = (props: TypePanelCloseButtonProps) => {
+  const panelContext = usePanelContext();
+
+  if (props.render) {
+    return props.render(panelContext) ?? null;
+  }
+
+  return (
+    <Button
+      appearance="pill"
+      aria-label={panelContext.closeButtonLabel}
+      onClick={panelContext.closePanel}
+      {...props}
+    >
+      {props.children || <Icon aria-hidden name="x-outline" />}
+    </Button>
+  );
+};
+
+PanelCloseButton.displayName = "Panel.CloseButton";

package/src/PanelContent.tsx

@@ -0,0 +1,18 @@
+import * as React from "react";
+import { Content } from "./styles";
+import type { TypePanelContentProps } from "./PanelTypes";
+
+export const PanelContent = ({ children, ...rest }: TypePanelContentProps) => (
+  <Content
+    flex="1 1 auto"
+    minHeight="0"
+    p={450}
+    color="text.body"
+    data-panel-content=""
+    {...rest}
+  >
+    {children}
+  </Content>
+);
+
+PanelContent.displayName = "Panel.Content";

package/src/PanelContext.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+import type { TypePanelContext } from "./PanelTypes";
+
+export const PanelContext = React.createContext<TypePanelContext | null>(null);
+
+export const usePanelContext = (): TypePanelContext => {
+  const ctx = React.useContext(PanelContext);
+  if (!ctx) {
+    throw new Error(
+      "usePanelContext must be used within a <PanelProvider>. Wrap the consuming tree in <PanelProvider> to provide isPanelOpen / togglePanel."
+    );
+  }
+  return ctx;
+};

package/src/PanelFooter.tsx

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { Footer } from "./styles";
+import type { TypePanelFooterProps } from "./PanelTypes";
+
+export const PanelFooter = ({ children, ...rest }: TypePanelFooterProps) => (
+  <Footer p={450} data-panel-footer="" {...rest}>
+    {children}
+  </Footer>
+);
+
+PanelFooter.displayName = "Panel.Footer";

package/src/PanelHeader.tsx

@@ -0,0 +1,41 @@
+import Box from "@sproutsocial/seeds-react-box";
+import Text from "@sproutsocial/seeds-react-text";
+import { usePanelContext } from "./PanelContext";
+import { PanelCloseButton } from "./PanelCloseButton";
+import type { TypePanelHeaderProps } from "./PanelTypes";
+
+export const PanelHeader = ({
+  title = "",
+  id = undefined,
+  children,
+  render,
+  ...rest
+}: TypePanelHeaderProps) => {
+  const panelContext = usePanelContext();
+
+  if (render) {
+    return render(panelContext);
+  }
+
+  return (
+    <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>
+  );
+};
+
+PanelHeader.displayName = "Panel.Header";

package/src/PanelMobileActionsHeader.tsx

@@ -0,0 +1,73 @@
+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";
+// eslint-disable-next-line import/no-deprecated
+import Text from "@sproutsocial/seeds-react-text";
+import type { TypeDrawerActionProps } from "@sproutsocial/seeds-react-drawer";
+
+interface TypePanelMobileActionsHeaderProps {
+  title?: string;
+  titleId?: string;
+  actions: TypeDrawerActionProps[];
+}
+
+/**
+ * Mobile bottom-sheet header used by Panel when `actionsInHeader` is set and
+ * no custom `header` is provided. Renders the title on the left and the
+ * forwarded actions plus a close button as pills on the right — mirrors the
+ * 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.
+ */
+export const PanelMobileActionsHeader = ({
+  title,
+  titleId,
+  actions,
+}: TypePanelMobileActionsHeaderProps) => (
+  <Drawer.Header
+    render={(ctx) => (
+      <Box
+        display="flex"
+        alignItems="center"
+        justifyContent="space-between"
+        pt={400}
+        px={450}
+        flex="0 0 auto"
+      >
+        <Text
+          as="h2"
+          fontSize={400}
+          fontWeight="semibold"
+          color="text.headline"
+          id={titleId}
+        >
+          {title}
+        </Text>
+        <Box display="flex" alignItems="center" gap={200}>
+          {actions.map((action, i) => (
+            <Button
+              key={i}
+              appearance="pill"
+              aria-label={action["aria-label"]}
+              onClick={action.onClick}
+              disabled={action.disabled}
+            >
+              {action.iconName && <Icon aria-hidden name={action.iconName} />}
+            </Button>
+          ))}
+          <Button
+            appearance="pill"
+            aria-label={ctx.closeButtonLabel}
+            onClick={ctx.onClose}
+          >
+            <Icon aria-hidden name="x-outline" />
+          </Button>
+        </Box>
+      </Box>
+    )}
+  />
+);
+
+PanelMobileActionsHeader.displayName = "PanelMobileActionsHeader";