@atlaskit/spotlight
Version:
A spotlight introduces users to points of interest, from focused messages to multi-step tours.
108 lines (107 loc) • 4.14 kB
TypeScript
/**
* @jsxRuntime classic
* @jsx jsx
*/
import { type ReactNode } from 'react';
import type { BackEvent, DismissEvent, DoneEvent, NextEvent, Placement } from '../../types';
/**
* Taken from `@atlaskit/popper`
*/
type Offset = [number | null | undefined, number | null | undefined];
type Strategy = 'absolute' | 'fixed';
interface BasePopoverContentProps {
/**
* A `testId` prop is provided for specified elements, which is a unique
* string that appears as a data attribute `data-testid` in the rendered code,
* serving as a hook for automated tests
*/
testId?: string;
/**
* The position in relation to the target the content should be shown at.
*/
placement: Placement;
/**
* Controls whether or not `PopoverContent` is visible. Defaults to `true`.
*/
isVisible?: boolean;
/**
* Controls whether the 'dismiss' action is invoked when the user clicks outside the content. Defaults to `true`.
*/
shouldDismissOnClickOutside?: boolean;
/**
* Spotlights can be dismissed by:
* - Clicking the `SpotlightDismissControl`
* - Clicking any DOM element outside the spotlight (if `shouldDismissOnClickOutside === true`)
* - Pressing the Escape key
*
* These events align to the React.MouseEvent<HTMLButtonElement, MouseEvent>, MouseEvent, and KeyboardEvent events respectively.
* Defaults to `true`.
*/
dismiss: (event: DismissEvent) => void;
/**
* Invoked when the user clicks `SpotlightSecondaryAction`. If an `onClick` handler is provided to `SpotlightSecondaryAction`
* then that takes precedence, and `back` will be ignored.
*/
back?: (event: BackEvent) => void;
/**
* Distance the spotlight should be offset from the target in the format of [along, away] (units in px).
* Defaults to [0, 2] - which means the spotlight will be 2px away from the edge of the target specified
* by the `placement` prop.
*
*/
offset?: Offset;
/**
* Describes the positioning strategy to use. By default, it is `fixed`, which positions the popper correctly when it's in the normal
* flow of the document. If your reference element is in an absolute container, like a modal, use the `absolute` strategy instead.
*
* For more details see: https://popper.js.org/docs/v2/constructors/#strategy
*
* @deprecated Has no effect when `platform-dst-top-layer-spotlight` is enabled.
*/
strategy?: Strategy;
/**
* The content to be rendered in `PopoverContent`. This is intended to be a `SpotlightCard`.
*
* Pass ONE element. On the top-layer code path it is rendered into a flex-row
* host so the viewport cap can reach it, and a fragment's children would become
* side-by-side flex items. See `children` on `Popover` in `@atlaskit/top-layer`.
*/
children: ReactNode;
/**
* The motion to be applied to the `SpotlightCard`.
*/
motion?: React.ComponentType<{
children: ReactNode;
}> | null;
}
export type PopoverContentProps = BasePopoverContentProps & ({
/**
* Invoked when the user clicks `SpotlightPrimaryAction` in a tour.
* If an `onClick` handler is provided to `SpotlightPrimaryAction` then that takes precedence,
* and `next` will be ignored.
*
* If `next` is passed to `PopoverContent`, then `done` cannot be passed. This will result in a type error.
*/
next: (event: NextEvent) => void;
/**
* Invoked when the user clicks `SpotlightPrimaryAction`.
* If an `onClick` handler is provided to SpotlightPrimaryAction then that takes precedence,
* and `done` will be ignored.
*
* If `done` is passed to PopoverContent, then `next` cannot be passed. This will result in a type error.
*/
done?: never;
} | {
done: (event: DoneEvent) => void;
next?: never;
} | {
next?: never;
done?: never;
});
/**
* __PopoverContent__
*
* A `PopoverContent` is the element that is shown as a popover.
*/
export declare const PopoverContent: (props: PopoverContentProps) => JSX.Element;
export {};