@sproutsocial/seeds-react-peek-in 0.5.1 → 0.6.0

package/dist/index.d.mts

@@ -33,6 +33,15 @@ type TypePeekInPanelToggleConfig = {
     "aria-label"?: string;
 };
 type TypePeekInProps = (TypePeekInControlledProps | TypePeekInUncontrolledProps) & {
+    /**
+     * Accessible label for the overlay dialog.
+     *
+     * Takes precedence over the label derived from `PeekInHeader`'s `title`.
+     * Required whenever the header `title` is not a plain string — a `ReactNode`
+     * title cannot be read as text, so without this the dialog has no meaningful
+     * accessible name.
+     */
+    "aria-label"?: string;
     /** Aria label for the built-in close button */
     closeButtonAriaLabel?: string;
     /** Additional action buttons shown in the action bar alongside the close button */
@@ -71,6 +80,13 @@ type TypePeekInProps = (TypePeekInControlledProps | TypePeekInUncontrolledProps)
 interface TypePeekInHeaderProps {
     /** Title displayed on the left side of the header */
     title: React.ReactNode;
+    /**
+     * Secondary text rendered beneath the title.
+     *
+     * Also used as a last-resort accessible name for the overlay when it is a
+     * plain string and neither `aria-label` nor a string `title` is available.
+     */
+    subtitle?: React.ReactNode;
     /** If provided, renders a back arrow button before the title */
     onBack?: () => void;
     /** Action buttons rendered on the right side of the header */
@@ -123,17 +139,85 @@ interface TypePeekInPanelProps {
     actionsInHeader?: boolean;
     children: React.ReactNode;
 }
+/**
+ * Props for PeekInFooter.
+ *
+ * Mirrors `TypeModalFooterProps` so Modal and PeekIn footers are learnable as
+ * one API. At least one of `primaryButton`, `cancelButton`, or `leftAction`
+ * must be supplied.
+ *
+ * Unlike ModalFooter this does not extend `TypeBoxProps`, matching the other
+ * PeekIn sub-components, which take domain props only.
+ */
+type TypePeekInFooterProps = {
+    /**
+     * Whether clicking the primary button closes the PeekIn.
+     * Set to `false` when the primary action is async and the overlay should stay
+     * open until it completes.
+     * @default true
+     */
+    closeOnPrimaryAction?: boolean;
+} & ({
+    /** Primary action, right-aligned. Closes the PeekIn unless `closeOnPrimaryAction` is false. */
+    primaryButton: React.ReactNode;
+    /** Cancel/secondary action, right-aligned. Always closes the PeekIn. */
+    cancelButton?: React.ReactNode;
+    /** Action pinned to the far left (e.g. Delete). Never closes the PeekIn. */
+    leftAction?: React.ReactNode;
+} | {
+    primaryButton?: React.ReactNode;
+    cancelButton: React.ReactNode;
+    leftAction?: React.ReactNode;
+} | {
+    primaryButton?: React.ReactNode;
+    cancelButton?: React.ReactNode;
+    leftAction: React.ReactNode;
+});
 interface TypePeekInTriggerProps {
     /** Element that opens the PeekIn when clicked */
     children: React.ReactNode;
 }
 
+/**
+ * Header for PeekIn's main column.
+ *
+ * Layout comes from the seeds-peek-in-* classes in peek-in.css rather than
+ * styled-system props on Box, so the header is Box-free on both render paths
+ * and the desktop header row matches how PeekInTailwind lays out the mobile
+ * bottom-sheet header. The title, subtitle, and back button still come from
+ * the composed Seeds primitives, which own their own styling.
+ */
 declare const PeekInHeader: React.FC<TypePeekInHeaderProps>;
 
 declare const PeekInContent: React.FC<TypePeekInContentProps>;
 
+/**
+ * Footer for PeekIn's main column, holding the overlay's primary actions.
+ *
+ * Slot behavior matches ModalFooter exactly:
+ * - `cancelButton` always closes
+ * - `primaryButton` closes unless `closeOnPrimaryAction` is false
+ * - `leftAction` never closes — the consumer owns it
+ *
+ * @example
+ * <PeekInFooter
+ *   leftAction={<Button appearance="destructive">Delete</Button>}
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button appearance="primary">Save</Button>}
+ * />
+ */
+declare const PeekInFooter: React.FC<TypePeekInFooterProps>;
+
 declare const PeekInPanel: React.FC<TypePeekInPanelProps>;
 
+/**
+ * Marks the element that opens the PeekIn.
+ *
+ * This is a slot marker, not a renderer. PeekIn reads `children` off this
+ * element and wires it up itself — as the Modal's trigger on desktop, and as a
+ * click-handled clone on mobile — so this component is never mounted on either
+ * path. It renders its children only as a defensive fallback for direct use.
+ */
 declare const PeekInTrigger: React.FC<TypePeekInTriggerProps>;
 
 /**
@@ -150,4 +234,4 @@ declare const PeekIn: {
     displayName: string;
 };
 
-export { PeekIn, PeekInContent, PeekInHeader, PeekInPanel, PeekInTrigger, type TypePeekInActionProps, type TypePeekInContentProps, type TypePeekInHeaderProps, type TypePeekInPanelProps, type TypePeekInPanelToggleConfig, type TypePeekInProps, type TypePeekInTriggerProps };
+export { PeekIn, PeekInContent, PeekInFooter, PeekInHeader, PeekInPanel, PeekInTrigger, type TypePeekInActionProps, type TypePeekInContentProps, type TypePeekInFooterProps, type TypePeekInHeaderProps, type TypePeekInPanelProps, type TypePeekInPanelToggleConfig, type TypePeekInProps, type TypePeekInTriggerProps };

package/dist/index.d.ts

@@ -33,6 +33,15 @@ type TypePeekInPanelToggleConfig = {
     "aria-label"?: string;
 };
 type TypePeekInProps = (TypePeekInControlledProps | TypePeekInUncontrolledProps) & {
+    /**
+     * Accessible label for the overlay dialog.
+     *
+     * Takes precedence over the label derived from `PeekInHeader`'s `title`.
+     * Required whenever the header `title` is not a plain string — a `ReactNode`
+     * title cannot be read as text, so without this the dialog has no meaningful
+     * accessible name.
+     */
+    "aria-label"?: string;
     /** Aria label for the built-in close button */
     closeButtonAriaLabel?: string;
     /** Additional action buttons shown in the action bar alongside the close button */
@@ -71,6 +80,13 @@ type TypePeekInProps = (TypePeekInControlledProps | TypePeekInUncontrolledProps)
 interface TypePeekInHeaderProps {
     /** Title displayed on the left side of the header */
     title: React.ReactNode;
+    /**
+     * Secondary text rendered beneath the title.
+     *
+     * Also used as a last-resort accessible name for the overlay when it is a
+     * plain string and neither `aria-label` nor a string `title` is available.
+     */
+    subtitle?: React.ReactNode;
     /** If provided, renders a back arrow button before the title */
     onBack?: () => void;
     /** Action buttons rendered on the right side of the header */
@@ -123,17 +139,85 @@ interface TypePeekInPanelProps {
     actionsInHeader?: boolean;
     children: React.ReactNode;
 }
+/**
+ * Props for PeekInFooter.
+ *
+ * Mirrors `TypeModalFooterProps` so Modal and PeekIn footers are learnable as
+ * one API. At least one of `primaryButton`, `cancelButton`, or `leftAction`
+ * must be supplied.
+ *
+ * Unlike ModalFooter this does not extend `TypeBoxProps`, matching the other
+ * PeekIn sub-components, which take domain props only.
+ */
+type TypePeekInFooterProps = {
+    /**
+     * Whether clicking the primary button closes the PeekIn.
+     * Set to `false` when the primary action is async and the overlay should stay
+     * open until it completes.
+     * @default true
+     */
+    closeOnPrimaryAction?: boolean;
+} & ({
+    /** Primary action, right-aligned. Closes the PeekIn unless `closeOnPrimaryAction` is false. */
+    primaryButton: React.ReactNode;
+    /** Cancel/secondary action, right-aligned. Always closes the PeekIn. */
+    cancelButton?: React.ReactNode;
+    /** Action pinned to the far left (e.g. Delete). Never closes the PeekIn. */
+    leftAction?: React.ReactNode;
+} | {
+    primaryButton?: React.ReactNode;
+    cancelButton: React.ReactNode;
+    leftAction?: React.ReactNode;
+} | {
+    primaryButton?: React.ReactNode;
+    cancelButton?: React.ReactNode;
+    leftAction: React.ReactNode;
+});
 interface TypePeekInTriggerProps {
     /** Element that opens the PeekIn when clicked */
     children: React.ReactNode;
 }
 
+/**
+ * Header for PeekIn's main column.
+ *
+ * Layout comes from the seeds-peek-in-* classes in peek-in.css rather than
+ * styled-system props on Box, so the header is Box-free on both render paths
+ * and the desktop header row matches how PeekInTailwind lays out the mobile
+ * bottom-sheet header. The title, subtitle, and back button still come from
+ * the composed Seeds primitives, which own their own styling.
+ */
 declare const PeekInHeader: React.FC<TypePeekInHeaderProps>;
 
 declare const PeekInContent: React.FC<TypePeekInContentProps>;
 
+/**
+ * Footer for PeekIn's main column, holding the overlay's primary actions.
+ *
+ * Slot behavior matches ModalFooter exactly:
+ * - `cancelButton` always closes
+ * - `primaryButton` closes unless `closeOnPrimaryAction` is false
+ * - `leftAction` never closes — the consumer owns it
+ *
+ * @example
+ * <PeekInFooter
+ *   leftAction={<Button appearance="destructive">Delete</Button>}
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button appearance="primary">Save</Button>}
+ * />
+ */
+declare const PeekInFooter: React.FC<TypePeekInFooterProps>;
+
 declare const PeekInPanel: React.FC<TypePeekInPanelProps>;
 
+/**
+ * Marks the element that opens the PeekIn.
+ *
+ * This is a slot marker, not a renderer. PeekIn reads `children` off this
+ * element and wires it up itself — as the Modal's trigger on desktop, and as a
+ * click-handled clone on mobile — so this component is never mounted on either
+ * path. It renders its children only as a defensive fallback for direct use.
+ */
 declare const PeekInTrigger: React.FC<TypePeekInTriggerProps>;
 
 /**
@@ -150,4 +234,4 @@ declare const PeekIn: {
     displayName: string;
 };
 
-export { PeekIn, PeekInContent, PeekInHeader, PeekInPanel, PeekInTrigger, type TypePeekInActionProps, type TypePeekInContentProps, type TypePeekInHeaderProps, type TypePeekInPanelProps, type TypePeekInPanelToggleConfig, type TypePeekInProps, type TypePeekInTriggerProps };
+export { PeekIn, PeekInContent, PeekInFooter, PeekInHeader, PeekInPanel, PeekInTrigger, type TypePeekInActionProps, type TypePeekInContentProps, type TypePeekInFooterProps, type TypePeekInHeaderProps, type TypePeekInPanelProps, type TypePeekInPanelToggleConfig, type TypePeekInProps, type TypePeekInTriggerProps };