@hypothesis/frontend-shared/lib/components/Thumbnail.d.ts

Shared components, styles and utilities for Hypothesis projects

/**
 * @typedef {import('preact').ComponentChildren} Children
 *
 * @typedef ThumbnailProps
 * @prop {Children|null} [children] - Thumbnail content (typically an img)
 * @prop {string} [classes] - Additional CSS classes to apply
 * @prop {boolean} [isLoading=false] - Is the thumbnail loading?
 * @prop {object} [placeholder='...'] - Optional placeholder to replace default
 * @prop {'small'|'medium'|'large'} [size='medium'] - Relative size of spinner
 *   to surrounding content. Typically the `large` size is appropriate, but for
 *   small thumbnails, `medium` might feel more appropriate.
 */
/**
 * Render a container with thumbnail content.
 *
 * Thumbnail content (e.g. img) may or may not be present. This component
 * provides support for three states:
 *
 *  - Content not yet loaded or is not available: Show a placeholder
 *  - Content is loading: Show a loading spinner
 *  - Content is present: Show the content, unless `isLoading` is `true`
 *
 * Thumbnail dimensions will remain constant even when content is not present,
 * avoiding layout shifts. Applied styling will constrain content to dimensions
 * of parent container. Apply explicit width and height rules to the parent
 * container of this component to dictate sizing.
 *
 * Examples:
 *
 * <Thumbnail><img src="http://placekitten.com/200/300" alt="kitty" /></Thumbnail>
 * <Thumbnail /> // -> Empty, shows placeholder
 * <Thumbnail isLoading /> // -> Empty, shows loading spinner
 *
 * TODO: There is an implied sub-pattern/-component here to do with rendering
 * embedded media within constraints, preventing layout shift, and handling
 * loading states. See https://github.com/hypothesis/frontend-shared/issues/134
 *
 * @param {ThumbnailProps} props
 */
export function Thumbnail({ children, classes, isLoading, placeholder, size, }: ThumbnailProps): import("preact").JSX.Element;
export type Children = import('preact').ComponentChildren;
export type ThumbnailProps = {
    /**
     * - Thumbnail content (typically an img)
     */
    children?: Children | null;
    /**
     * - Additional CSS classes to apply
     */
    classes?: string | undefined;
    /**
     * - Is the thumbnail loading?
     */
    isLoading?: boolean | undefined;
    /**
     * - Optional placeholder to replace default
     */
    placeholder?: object;
    /**
     * - Relative size of spinner
     * to surrounding content. Typically the `large` size is appropriate, but for
     * small thumbnails, `medium` might feel more appropriate.
     */
    size?: "small" | "medium" | "large" | undefined;
};