@sproutsocial/seeds-react-panel 0.3.7

package/src/PanelProvider.tsx

@@ -0,0 +1,38 @@
+import * as React from "react";
+import { PanelContext } from "./PanelContext";
+import type { TypePanelContext, TypePanelProviderProps } from "./PanelTypes";
+
+export const PanelProvider = ({
+  children,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+}: TypePanelProviderProps) => {
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const isPanelOpen = isControlled ? controlledOpen : internalOpen;
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  const openPanel = React.useCallback(() => setOpen(true), [setOpen]);
+  const closePanel = React.useCallback(() => setOpen(false), [setOpen]);
+  const togglePanel = React.useCallback(
+    () => setOpen(!isPanelOpen),
+    [setOpen, isPanelOpen]
+  );
+
+  const value = React.useMemo<TypePanelContext>(
+    () => ({ isPanelOpen, openPanel, closePanel, togglePanel }),
+    [isPanelOpen, openPanel, closePanel, togglePanel]
+  );
+
+  return (
+    <PanelContext.Provider value={value}>{children}</PanelContext.Provider>
+  );
+};

package/src/PanelTypes.ts

@@ -0,0 +1,166 @@
+import * as React from "react";
+import type {
+  TypeSystemCommonProps,
+  TypeStyledComponentsCommonProps,
+} from "@sproutsocial/seeds-react-system-props";
+import type { TypeBoxProps } from "@sproutsocial/seeds-react-box";
+import type { TypeButtonProps } from "@sproutsocial/seeds-react-button";
+import type {
+  TypeDrawerSnapPoint,
+  TypeDrawerActionProps,
+} from "@sproutsocial/seeds-react-drawer";
+
+export type { TypeDrawerActionProps as TypePanelActionProps };
+
+export type PanelDirection = "left" | "right" | "bottom";
+
+export interface TypePanelContext {
+  isPanelOpen: boolean;
+  togglePanel: () => void;
+  openPanel: () => void;
+  closePanel: () => void;
+  closeButtonLabel?: string;
+}
+
+export interface TypePanelProviderProps {
+  children: React.ReactNode;
+  /** Initial open state for uncontrolled usage. */
+  defaultOpen?: boolean;
+  /** Controlled open state. When provided, the provider becomes controlled. */
+  open?: boolean;
+  /** Called whenever the open state changes. Required for controlled usage. */
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface TypePanelProps
+  extends TypeStyledComponentsCommonProps,
+    TypeSystemCommonProps,
+    Omit<React.ComponentPropsWithoutRef<"div">, "color"> {
+  children: React.ReactNode;
+
+  /** Label for the close button. Usually "Close". */
+  closeButtonLabel: string;
+
+  /**
+   * Custom header content. When provided, replaces the auto-rendered default
+   * header entirely — `title` and `titleId` are ignored.
+   */
+  header?: React.ReactNode;
+
+  /** Custom footer content. Not rendered when omitted. */
+  footer?: React.ReactNode;
+
+  /** Title shown in the auto-rendered default header. Ignored when `header` is provided. */
+  title?: string;
+
+  /**
+   * Sets the `id` on the title element of the auto-rendered header. When the
+   * default header is used, Panel automatically wires `aria-labelledby` to this
+   * id so the dialog/aside has an accessible name. Pass an explicit
+   * `aria-labelledby` to override (e.g. when pointing at a different element).
+   * Ignored when `header` is provided — supply your own `aria-labelledby` in
+   * that case.
+   */
+  titleId?: string;
+
+  /** Side the panel anchors to on desktop. Defaults to "right". */
+  direction?: PanelDirection;
+
+  /**
+   * Width (px) when direction is "left" or "right", or height (px) when
+   * direction is "bottom". Defaults to 384 to match the existing web-app-core
+   * Panel.
+   */
+  width?: number;
+
+  /**
+   * Visual gap (px) between the panel and the adjacent content. Applied as
+   * margin on the side facing the content (left when direction="right",
+   * right when direction="left", top when direction="bottom"). Animates with
+   * the panel's open/close transition and collapses to 0 when closed so the
+   * gap does not remain visible alongside a zero-width panel. Defaults to 0.
+   */
+  gap?: number;
+
+  /**
+   * Forwarded to `useIsMobile`. Accepts a px number or any CSS media-query
+   * length. Below this width, the panel renders as an overlay bottom sheet
+   * (via seeds-react-drawer). Defaults to the theme's `breakpoints.sm`.
+   */
+  mobileBreakpoint?: number | string;
+
+  /** Applies only to the mobile bottom-sheet rendering. */
+  zIndex?: number;
+
+  /** Optional id used for data-qa-panel attributes. */
+  id?: string;
+
+  /**
+   * Snap points the panel can rest at when rendered as a mobile bottom sheet.
+   * Numbers 0–1 are viewport-height fractions; numbers > 1 are pixels; strings
+   * accept `px`/`rem` (e.g. `"480px"`, `"30rem"`). Order matters — the last
+   * entry is the "expanded" state. Ignored on the desktop side-panel rendering.
+   */
+  snapPoints?: TypeDrawerSnapPoint[];
+
+  /** Initial snap point for uncontrolled use. Mobile only. */
+  defaultSnapPoint?: TypeDrawerSnapPoint | null;
+
+  /** Controlled active snap point. Pair with `onSnapPointChange`. Mobile only. */
+  snapPoint?: TypeDrawerSnapPoint | null;
+
+  /** Fires when the active snap point changes. Mobile only. */
+  onSnapPointChange?: (snapPoint: TypeDrawerSnapPoint | null) => void;
+
+  /**
+   * When true, fast swipes can't skip past adjacent snap points. Mobile only.
+   */
+  snapToSequentialPoints?: boolean;
+
+  /**
+   * Action buttons shown in a floating rail above the panel on mobile (the
+   * bottom-sheet rendering). Ignored on desktop side-panel rendering — pass
+   * actions through `header`/`footer` slots there. The rail owns the close
+   * button so the default header omits its built-in close affordance.
+   */
+  actions?: TypeDrawerActionProps[];
+
+  /**
+   * Opt out of the floating mobile rail and render the `actions` inline in the
+   * header as pill buttons instead. Useful for nested bottom sheets and
+   * snap-point layouts where the floating rail would collide with surrounding
+   * UI. Defaults to `false`.
+   *
+   * When `header` is omitted, Panel auto-composes a mobile header that renders
+   * the title, the `actions` as pills, and a close-button pill. When `header`
+   * is provided, the consumer is responsible for rendering the actions inside
+   * their own header — `actions` is forwarded for context only.
+   */
+  actionsInHeader?: boolean;
+}
+
+export interface TypePanelHeaderProps extends TypeBoxProps {
+  title?: string;
+  /**
+   * When children are provided, `<Panel.CloseButton />` is NOT rendered
+   * automatically. Include it yourself to preserve keyboard accessibility.
+   */
+  children?: React.ReactNode;
+  /** Render-prop override that receives the parent panel context. */
+  render?: React.FC<TypePanelContext>;
+}
+
+export interface TypePanelContentProps extends TypeBoxProps {
+  children?: React.ReactNode;
+}
+
+export interface TypePanelFooterProps extends TypeBoxProps {
+  children?: React.ReactNode;
+}
+
+export interface TypePanelCloseButtonProps
+  extends Omit<TypeButtonProps, "children"> {
+  /** Render-prop override that receives the parent panel context. */
+  render?: React.FC<TypePanelContext>;
+  children?: React.ReactNode;
+}

package/src/__tests__/Panel.test.tsx

@@ -0,0 +1,354 @@
+/* eslint-disable testing-library/prefer-screen-queries */
+
+import React from "react";
+import {
+  render as testRender,
+  waitFor,
+  screen,
+  act,
+} from "@sproutsocial/seeds-react-testing-library";
+import Panel, { PanelProvider, usePanelContext } from "../index";
+import type { TypePanelProps } from "../PanelTypes";
+
+const ToggleButton = ({ label = "toggle" }: { label?: string }) => {
+  const { togglePanel } = usePanelContext();
+  return <button onClick={togglePanel}>{label}</button>;
+};
+
+const renderPanel = ({
+  defaultOpen = false,
+  direction,
+  width,
+  children = (
+    <Panel.Content>
+      <p>Panel Content</p>
+    </Panel.Content>
+  ),
+  title = "Panel Header",
+  titleId = "panel-1-header",
+  closeButtonLabel = "close button",
+  ...rest
+}: Partial<TypePanelProps> & { defaultOpen?: boolean } = {}) => {
+  return testRender(
+    <PanelProvider defaultOpen={defaultOpen}>
+      <div>
+        <ToggleButton />
+        <Panel
+          closeButtonLabel={closeButtonLabel}
+          direction={direction}
+          width={width}
+          title={title}
+          titleId={titleId}
+          {...rest}
+        >
+          {children}
+        </Panel>
+      </div>
+    </PanelProvider>
+  );
+};
+
+describe("Panel (desktop / inline mode)", () => {
+  it("renders children when open by default", () => {
+    renderPanel({ defaultOpen: true });
+    expect(screen.getByText(/panel content/i)).toBeInTheDocument();
+  });
+
+  it("toggles open and closed via context", async () => {
+    const { user } = renderPanel({ defaultOpen: false });
+    const panel = screen.getByRole("complementary");
+    expect(panel).toHaveAttribute("data-qa-panel-isopen", "false");
+
+    await act(async () => {
+      await user.click(screen.getByText("toggle"));
+    });
+
+    await waitFor(() => {
+      expect(panel).toHaveAttribute("data-qa-panel-isopen", "true");
+    });
+    expect(screen.getByText(/panel content/i)).toBeInTheDocument();
+  });
+
+  it("close button calls closePanel from context", async () => {
+    const { user } = renderPanel({ defaultOpen: true });
+
+    expect(screen.getByRole("complementary")).toHaveAttribute(
+      "data-qa-panel-isopen",
+      "true"
+    );
+
+    await act(async () => {
+      await user.click(screen.getByLabelText("close button"));
+    });
+
+    await waitFor(() => {
+      expect(screen.getByRole("complementary")).toHaveAttribute(
+        "data-qa-panel-isopen",
+        "false"
+      );
+    });
+  });
+
+  it("renders the title element with the provided id", () => {
+    renderPanel({ defaultOpen: true });
+    expect(screen.getByText("Panel Header")).toHaveAttribute(
+      "id",
+      "panel-1-header"
+    );
+  });
+
+  it("Panel.Content sets data-panel-content attribute", () => {
+    renderPanel({ defaultOpen: true });
+    expect(
+      screen.getByText(/panel content/i).closest("[data-panel-content]")
+    ).toBeInTheDocument();
+  });
+
+  it("accepts a custom header via the header prop", async () => {
+    const { user } = renderPanel({
+      defaultOpen: true,
+      header: (
+        <Panel.Header>
+          <h1>Custom Title</h1>
+          <Panel.CloseButton />
+        </Panel.Header>
+      ),
+    });
+
+    expect(screen.getByText("Custom Title")).toBeInTheDocument();
+
+    await act(async () => {
+      await user.click(screen.getByLabelText("close button"));
+    });
+
+    await waitFor(() => {
+      expect(screen.getByRole("complementary")).toHaveAttribute(
+        "data-qa-panel-isopen",
+        "false"
+      );
+    });
+  });
+
+  it("uses the provided width on desktop", () => {
+    renderPanel({ defaultOpen: true, width: 500 });
+    expect(screen.getByRole("complementary")).toHaveStyle("flex-basis: 500px");
+  });
+
+  it("collapses to flex-basis: 0 when closed", () => {
+    renderPanel({ defaultOpen: false });
+    expect(screen.getByRole("complementary")).toHaveStyle("flex-basis: 0px");
+  });
+});
+
+describe("Panel (mobile / drawer mode)", () => {
+  let originalMatchMedia: typeof window.matchMedia | undefined;
+
+  beforeEach(() => {
+    originalMatchMedia = window.matchMedia;
+    window.matchMedia = jest.fn().mockImplementation((query: string) => ({
+      matches: true,
+      media: query,
+      onchange: null,
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+  });
+
+  afterEach(() => {
+    if (originalMatchMedia) {
+      window.matchMedia = originalMatchMedia;
+    } else {
+      // @ts-expect-error allow deleting a non-optional dom property in tests
+      delete window.matchMedia;
+    }
+  });
+
+  it("defaults aria-labelledby to titleId when the default header is used", () => {
+    renderPanel({ defaultOpen: true });
+
+    expect(screen.getByRole("dialog")).toHaveAttribute(
+      "aria-labelledby",
+      "panel-1-header"
+    );
+  });
+
+  it("does not emit Drawer's missing-accessible-name warning", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    renderPanel({ defaultOpen: true });
+    expect(warnSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining("[Drawer] Missing accessible name")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("consumer aria-labelledby wins over the titleId default", () => {
+    renderPanel({
+      defaultOpen: true,
+      "aria-labelledby": "external-heading",
+    });
+
+    expect(screen.getByRole("dialog")).toHaveAttribute(
+      "aria-labelledby",
+      "external-heading"
+    );
+  });
+
+  it("forwards aria-label to the Drawer", () => {
+    renderPanel({
+      defaultOpen: true,
+      "aria-label": "Inspector",
+    });
+
+    expect(screen.getByRole("dialog")).toHaveAttribute(
+      "aria-label",
+      "Inspector"
+    );
+  });
+
+  it("forwards arbitrary data-* props to the Drawer", () => {
+    renderPanel({
+      defaultOpen: true,
+      // @ts-expect-error custom data attribute not in the typed prop list
+      "data-testid": "panel-mobile",
+    });
+
+    expect(screen.getByTestId("panel-mobile")).toBeInTheDocument();
+  });
+
+  it("does not default aria-labelledby when a custom header is provided", () => {
+    renderPanel({
+      defaultOpen: true,
+      header: <div>Custom Header</div>,
+    });
+
+    expect(screen.getByRole("dialog")).not.toHaveAttribute("aria-labelledby");
+  });
+
+  it("renders actions as pills in the header when actionsInHeader is set", async () => {
+    const onExpand = jest.fn();
+    const onShare = jest.fn();
+    const { user } = renderPanel({
+      defaultOpen: true,
+      actionsInHeader: true,
+      actions: [
+        {
+          "aria-label": "Expand",
+          iconName: "arrows-pointing-out-outline",
+          onClick: onExpand,
+        },
+        {
+          "aria-label": "Share",
+          iconName: "link-outline",
+          onClick: onShare,
+        },
+      ],
+    });
+
+    const expand = screen.getByLabelText("Expand");
+    const share = screen.getByLabelText("Share");
+    expect(expand).toBeInTheDocument();
+    expect(share).toBeInTheDocument();
+    // The auto-composed header also renders its own close pill so the
+    // suppressed-rail combination still has a way to dismiss the sheet.
+    expect(screen.getByLabelText("close button")).toBeInTheDocument();
+
+    await act(async () => {
+      await user.click(expand);
+    });
+    expect(onExpand).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      await user.click(share);
+    });
+    expect(onShare).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards actions to the floating rail when actionsInHeader is not set", () => {
+    renderPanel({
+      defaultOpen: true,
+      actions: [
+        {
+          "aria-label": "Expand",
+          iconName: "arrows-pointing-out-outline",
+        },
+      ],
+    });
+
+    // Rail-mode: the rail owns the close button (with closeButtonLabel) and
+    // the action button is rendered inside the rail rather than as a header
+    // pill. Both are present, the rail's aria-label is set, and the
+    // auto-composed header is not used (no duplicate close pill).
+    expect(screen.getByLabelText("Drawer quick actions")).toBeInTheDocument();
+    expect(screen.getByLabelText("Expand")).toBeInTheDocument();
+    expect(screen.getAllByLabelText("close button")).toHaveLength(1);
+  });
+
+  it("does not auto-render the actions header when a custom header is provided", () => {
+    renderPanel({
+      defaultOpen: true,
+      actionsInHeader: true,
+      actions: [
+        {
+          "aria-label": "Expand",
+          iconName: "arrows-pointing-out-outline",
+        },
+      ],
+      header: <div>Custom Header</div>,
+    });
+
+    expect(screen.getByText("Custom Header")).toBeInTheDocument();
+    // The consumer owns rendering — Panel must not duplicate the action pill.
+    expect(screen.queryByLabelText("Expand")).not.toBeInTheDocument();
+  });
+});
+
+describe("PanelProvider (controlled)", () => {
+  it("calls onOpenChange when the panel toggles", async () => {
+    const onOpenChange = jest.fn();
+    const Controlled = () => {
+      const [open, setOpen] = React.useState(false);
+      return (
+        <PanelProvider
+          open={open}
+          onOpenChange={(next) => {
+            onOpenChange(next);
+            setOpen(next);
+          }}
+        >
+          <ToggleButton />
+          <Panel closeButtonLabel="close button">
+            <Panel.Content>
+              <p>controlled content</p>
+            </Panel.Content>
+          </Panel>
+        </PanelProvider>
+      );
+    };
+
+    const { user } = testRender(<Controlled />);
+    await act(async () => {
+      await user.click(screen.getByText("toggle"));
+    });
+
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+});
+
+describe("usePanelContext", () => {
+  it("throws when used outside a PanelProvider", () => {
+    const Crash = () => {
+      usePanelContext();
+      return null;
+    };
+
+    // Suppress React's expected error console output for this assertion.
+    const spy = jest.spyOn(console, "error").mockImplementation(() => {});
+    expect(() => testRender(<Crash />)).toThrow(
+      /usePanelContext must be used within a <PanelProvider>/
+    );
+    spy.mockRestore();
+  });
+});

package/src/__tests__/Panel.typetest.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+import Panel, {
+  PanelProvider,
+  usePanelContext,
+  type TypePanelProps,
+  type PanelDirection,
+} from "../index";
+
+// Compile-only type assertions. Not executed; presence of `_` flags unused warnings.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function _typeTests() {
+  // Required prop: closeButtonLabel
+  // @ts-expect-error closeButtonLabel is required
+  const _missing: React.ReactElement = <Panel>content</Panel>;
+
+  // Valid directions only
+  const _dir: PanelDirection = "right";
+  // @ts-expect-error "top" is not a supported direction
+  const _badDir: PanelDirection = "top";
+
+  // PanelProvider props
+  const _provider = (
+    <PanelProvider defaultOpen open={false} onOpenChange={() => {}}>
+      child
+    </PanelProvider>
+  );
+
+  // usePanelContext shape
+  const ctx: ReturnType<typeof usePanelContext> = {
+    isPanelOpen: true,
+    openPanel: () => {},
+    closePanel: () => {},
+    togglePanel: () => {},
+  };
+  void ctx;
+
+  // Full Panel props
+  const _props: TypePanelProps = {
+    children: null,
+    closeButtonLabel: "Close",
+    direction: "left",
+    width: 384,
+    mobileBreakpoint: 640,
+  };
+  void _props;
+  void _missing;
+  void _dir;
+  void _badDir;
+  void _provider;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import Panel from "./Panel";
+
+export default Panel;
+export { Panel };
+export { PanelContext, usePanelContext } from "./PanelContext";
+export { PanelProvider } from "./PanelProvider";
+export { PanelHeader } from "./PanelHeader";
+export { PanelContent } from "./PanelContent";
+export { PanelCloseButton } from "./PanelCloseButton";
+export { PanelFooter } from "./PanelFooter";
+export * from "./PanelTypes";

package/src/styles.ts

@@ -0,0 +1,71 @@
+import styled, { css } from "styled-components";
+import { COMMON } from "@sproutsocial/seeds-react-system-props";
+import type { TypeSystemCommonProps } from "@sproutsocial/seeds-react-system-props";
+import { MOTION_DURATION_MEDIUM } from "@sproutsocial/seeds-motion/unitless";
+import Box from "@sproutsocial/seeds-react-box";
+import type { PanelDirection } from "./PanelTypes";
+
+interface PanelContainerProps extends TypeSystemCommonProps {
+  $isOpen: boolean;
+  $direction: PanelDirection;
+  $width: number;
+  $gap: number;
+}
+
+const gapSide = (direction: PanelDirection): "left" | "right" | "top" => {
+  if (direction === "right") return "left";
+  if (direction === "left") return "right";
+  return "top";
+};
+
+export const PanelContainer = styled.aside<PanelContainerProps>`
+  background: ${(props) => props.theme.colors.container.background.base};
+  flex-grow: 0;
+  flex-shrink: 0;
+  overflow: hidden;
+  transition: flex-basis ${MOTION_DURATION_MEDIUM}s ease-in-out,
+    margin ${MOTION_DURATION_MEDIUM}s ease-in-out;
+  flex-basis: ${(props) => (props.$isOpen ? `${props.$width}px` : "0px")};
+  margin-${(props) => gapSide(props.$direction)}: ${(props) =>
+  props.$isOpen && props.$gap ? `${props.$gap}px` : "0px"};
+  border-radius: ${({ theme }) => theme.radii[800]};
+
+  ${(props) =>
+    props.$direction === "bottom"
+      ? css`
+          width: 100%;
+        `
+      : css`
+          height: 100%;
+        `}
+
+  ${COMMON}
+`;
+
+export const PanelInner = styled.div<{
+  $direction: PanelDirection;
+  $width: number;
+}>`
+  ${(props) =>
+    props.$direction === "bottom"
+      ? css`
+          min-height: ${props.$width}px;
+          width: 100%;
+        `
+      : css`
+          min-width: ${props.$width}px;
+          height: 100%;
+        `}
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+`;
+
+export const Content = styled(Box)`
+  overflow-y: auto;
+`;
+
+export const Footer = styled(Box)`
+  flex: 0 0 auto;
+  overflow: hidden;
+`;