@sproutsocial/seeds-react-panel 0.3.7

package/dist/index.d.mts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import { TypeStyledComponentsCommonProps, TypeSystemCommonProps } from '@sproutsocial/seeds-react-system-props';
+import { TypeBoxProps } from '@sproutsocial/seeds-react-box';
+import { TypeButtonProps } from '@sproutsocial/seeds-react-button';
+import { TypeDrawerSnapPoint, TypeDrawerActionProps } from '@sproutsocial/seeds-react-drawer';
+export { TypeDrawerActionProps as TypePanelActionProps } from '@sproutsocial/seeds-react-drawer';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type PanelDirection = "left" | "right" | "bottom";
+interface TypePanelContext {
+    isPanelOpen: boolean;
+    togglePanel: () => void;
+    openPanel: () => void;
+    closePanel: () => void;
+    closeButtonLabel?: string;
+}
+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;
+}
+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;
+}
+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>;
+}
+interface TypePanelContentProps extends TypeBoxProps {
+    children?: React.ReactNode;
+}
+interface TypePanelFooterProps extends TypeBoxProps {
+    children?: React.ReactNode;
+}
+interface TypePanelCloseButtonProps extends Omit<TypeButtonProps, "children"> {
+    /** Render-prop override that receives the parent panel context. */
+    render?: React.FC<TypePanelContext>;
+    children?: React.ReactNode;
+}
+
+declare const PanelComponent: {
+    ({ children, closeButtonLabel, header, footer, title, titleId, direction, width, gap, mobileBreakpoint, zIndex, id, snapPoints, defaultSnapPoint, snapPoint, onSnapPointChange, snapToSequentialPoints, actions, actionsInHeader, "aria-labelledby": ariaLabelledByProp, "aria-label": ariaLabel, ...rest }: TypePanelProps): react_jsx_runtime.JSX.Element;
+    Header: {
+        ({ title, id, children, render, ...rest }: TypePanelHeaderProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+        displayName: string;
+    };
+    Content: {
+        ({ children, ...rest }: TypePanelContentProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    CloseButton: {
+        (props: TypePanelCloseButtonProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null;
+        displayName: string;
+    };
+    Footer: {
+        ({ children, ...rest }: TypePanelFooterProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+
+declare const PanelContext: React.Context<TypePanelContext | null>;
+declare const usePanelContext: () => TypePanelContext;
+
+declare const PanelProvider: ({ children, defaultOpen, open: controlledOpen, onOpenChange, }: TypePanelProviderProps) => react_jsx_runtime.JSX.Element;
+
+declare const PanelHeader: {
+    ({ title, id, children, render, ...rest }: TypePanelHeaderProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+    displayName: string;
+};
+
+declare const PanelContent: {
+    ({ children, ...rest }: TypePanelContentProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+declare const PanelCloseButton: {
+    (props: TypePanelCloseButtonProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null;
+    displayName: string;
+};
+
+declare const PanelFooter: {
+    ({ children, ...rest }: TypePanelFooterProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+export { PanelComponent as Panel, PanelCloseButton, PanelContent, PanelContext, type PanelDirection, PanelFooter, PanelHeader, PanelProvider, type TypePanelCloseButtonProps, type TypePanelContentProps, type TypePanelContext, type TypePanelFooterProps, type TypePanelHeaderProps, type TypePanelProps, type TypePanelProviderProps, PanelComponent as default, usePanelContext };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import { TypeStyledComponentsCommonProps, TypeSystemCommonProps } from '@sproutsocial/seeds-react-system-props';
+import { TypeBoxProps } from '@sproutsocial/seeds-react-box';
+import { TypeButtonProps } from '@sproutsocial/seeds-react-button';
+import { TypeDrawerSnapPoint, TypeDrawerActionProps } from '@sproutsocial/seeds-react-drawer';
+export { TypeDrawerActionProps as TypePanelActionProps } from '@sproutsocial/seeds-react-drawer';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type PanelDirection = "left" | "right" | "bottom";
+interface TypePanelContext {
+    isPanelOpen: boolean;
+    togglePanel: () => void;
+    openPanel: () => void;
+    closePanel: () => void;
+    closeButtonLabel?: string;
+}
+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;
+}
+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;
+}
+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>;
+}
+interface TypePanelContentProps extends TypeBoxProps {
+    children?: React.ReactNode;
+}
+interface TypePanelFooterProps extends TypeBoxProps {
+    children?: React.ReactNode;
+}
+interface TypePanelCloseButtonProps extends Omit<TypeButtonProps, "children"> {
+    /** Render-prop override that receives the parent panel context. */
+    render?: React.FC<TypePanelContext>;
+    children?: React.ReactNode;
+}
+
+declare const PanelComponent: {
+    ({ children, closeButtonLabel, header, footer, title, titleId, direction, width, gap, mobileBreakpoint, zIndex, id, snapPoints, defaultSnapPoint, snapPoint, onSnapPointChange, snapToSequentialPoints, actions, actionsInHeader, "aria-labelledby": ariaLabelledByProp, "aria-label": ariaLabel, ...rest }: TypePanelProps): react_jsx_runtime.JSX.Element;
+    Header: {
+        ({ title, id, children, render, ...rest }: TypePanelHeaderProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+        displayName: string;
+    };
+    Content: {
+        ({ children, ...rest }: TypePanelContentProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    CloseButton: {
+        (props: TypePanelCloseButtonProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null;
+        displayName: string;
+    };
+    Footer: {
+        ({ children, ...rest }: TypePanelFooterProps): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+
+declare const PanelContext: React.Context<TypePanelContext | null>;
+declare const usePanelContext: () => TypePanelContext;
+
+declare const PanelProvider: ({ children, defaultOpen, open: controlledOpen, onOpenChange, }: TypePanelProviderProps) => react_jsx_runtime.JSX.Element;
+
+declare const PanelHeader: {
+    ({ title, id, children, render, ...rest }: TypePanelHeaderProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+    displayName: string;
+};
+
+declare const PanelContent: {
+    ({ children, ...rest }: TypePanelContentProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+declare const PanelCloseButton: {
+    (props: TypePanelCloseButtonProps): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null;
+    displayName: string;
+};
+
+declare const PanelFooter: {
+    ({ children, ...rest }: TypePanelFooterProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+export { PanelComponent as Panel, PanelCloseButton, PanelContent, PanelContext, type PanelDirection, PanelFooter, PanelHeader, PanelProvider, type TypePanelCloseButtonProps, type TypePanelContentProps, type TypePanelContext, type TypePanelFooterProps, type TypePanelHeaderProps, type TypePanelProps, type TypePanelProviderProps, PanelComponent as default, usePanelContext };