@hypothesis/frontend-shared/lib/pattern-library/components/Library.d.ts

Shared components, styles and utilities for Hypothesis projects

import type { ComponentChildren, JSX } from 'preact';
/**
 * Components for rendering component documentation, examples and demos in the
 * pattern-library page.
 */
type LibraryElementAttributes = Omit<JSX.HTMLAttributes<HTMLElement>, 'title'>;
export type LibraryPageProps = {
    children?: ComponentChildren;
    intro?: ComponentChildren;
    title?: string;
};
/**
 * Render content for a pattern-library page
 */
declare function Page({ children, intro, title }: LibraryPageProps): JSX.Element;
export type LibraryHeadingProps = JSX.HTMLAttributes<HTMLHeadingElement> & {
    children: ComponentChildren;
    level: number;
};
export type LibrarySectionProps = LibraryElementAttributes & {
    children?: ComponentChildren;
    intro?: ComponentChildren;
    title?: string;
    level?: number;
};
/**
 * Render a primary section of a page. Each component documented on a pattern-
 * library page gets its own section.
 */
declare function Section({ children, intro, level, title, ...htmlAttributes }: LibrarySectionProps): JSX.Element;
export type LibrarySectionL2Props = LibraryElementAttributes & {
    children?: ComponentChildren;
    title?: string;
};
/**
 * Render a second-level section. e.g. Usage, Props, Status
 */
declare function SectionL2({ children, title, ...htmlAttributes }: LibrarySectionL2Props): JSX.Element;
export type LibrarySectionL3Props = LibraryElementAttributes & {
    children?: ComponentChildren;
    title?: string;
};
/**
 * Render content in a third-level section, e.g. documentation
 * about a specific prop or examples of usage.
 */
declare function SectionL3({ children, title, ...htmlAttributes }: LibrarySectionL3Props): JSX.Element;
export type LibraryDemoProps = {
    children?: ComponentChildren;
    /**
     * Example file to read and use as content (to be rendered with syntax
     * highlighting).
     * It should be relative to the `pattern-library/examples` dir, and include no
     * file extension: `exampleFile="some-example"`.
     *
     * The file needs to have a default export, which will be used to render the
     * interactive example.
     *
     * If provided together with `children`, `children` will take precedence.
     */
    exampleFile?: string;
    /** Extra CSS classes for the demo content's immediate parent container */
    classes?: string | string[];
    /** Inline styles to apply to the demo container */
    style?: JSX.CSSProperties;
    title?: ComponentChildren;
    /**
     * Should the demo also render the source? When true, a "Source" tab will be
     * rendered, which will display the JSX source of the Demo's children.
     */
    withSource?: boolean;
};
/**
 * Render a "Demo", with optional source. This will render the children as
 * provided in a tabbed container. If `withSource` is `true`, the JSX source
 * of the children will be provided in a separate "Source" tab from the
 * rendered Demo content.
 */
declare function Demo({ classes, withSource, style, title, ...rest }: LibraryDemoProps): JSX.Element;
type ChangeStatus = 'breaking' | 'added' | 'changed' | 'deprecated';
type LibraryStatusChipProps = {
    status: ChangeStatus;
};
/**
 * Render a pill to highlight a change
 */
declare function StatusChip({ status }: LibraryStatusChipProps): JSX.Element;
export type LibraryChangelogProps = {
    children: ComponentChildren;
};
/**
 * Wrapper around a list of changelog items
 */
declare function Changelog({ children }: LibraryChangelogProps): JSX.Element;
export type LibraryChangelogItemProps = {
    status: ChangeStatus;
    children: ComponentChildren;
};
/**
 * Single changelog item
 */
declare function ChangelogItem({ status, children }: LibraryChangelogItemProps): JSX.Element;
type CodeContentProps = {
    /** Code content (to be rendered with syntax highlighting) */
    content: ComponentChildren;
} | {
    /**
     * Example file to read and use as content (to be rendered with syntax
     * highlighting)
     */
    exampleFile: string;
};
export type LibraryCodeProps = {
    /** Controls relative code font size */
    size?: 'sm' | 'md';
    /** Caption (e.g. filename, description) of code block */
    title?: ComponentChildren;
} & CodeContentProps;
/**
 * Render provided `content` as a "code block" example.
 *
 * Long code content will scroll if <Code /> is rendered inside a parent
 * element with constrained dimensions.
 */
declare function Code({ size, title, ...rest }: LibraryCodeProps): JSX.Element;
export type LibraryUsageProps = {
    /** @deprecated. Use symbolName instead */
    componentName?: string;
    symbolName?: string;
    size?: 'sm' | 'md';
};
/**
 * Render import "usage" of a given `componentName`
 */
declare function Usage({ componentName, symbolName, size, }: LibraryUsageProps): JSX.Element;
export type LinkProps = {
    children: ComponentChildren;
    href: string;
};
/**
 * Render an internal link to another pattern-library page.
 * TODO: Support external links
 */
declare function Link({ children, href }: LinkProps): JSX.Element;
declare function Callout({ children }: {
    children: ComponentChildren;
}): JSX.Element;
/**
 * Render a two-column grid for label-description pairs
 */
declare function Info({ children }: {
    children: ComponentChildren;
}): JSX.Element;
/**
 * Render a "row" in an Info layout with a label and description (children)
 */
declare function InfoItem({ children, label, }: {
    children: ComponentChildren;
    label: string;
}): JSX.Element;
declare const _default: {
    Callout: typeof Callout;
    Changelog: typeof Changelog;
    ChangelogItem: typeof ChangelogItem;
    Code: typeof Code;
    Demo: typeof Demo;
    Info: typeof Info;
    InfoItem: typeof InfoItem;
    Link: typeof Link;
    Page: typeof Page;
    Section: typeof Section;
    SectionL2: typeof SectionL2;
    SectionL3: typeof SectionL3;
    StatusChip: typeof StatusChip;
    Usage: typeof Usage;
};
export default _default;