@epicbagel/saas-kit 1.31.0 → 1.33.0

package/dist/primitives/poster.d.cts

@@ -0,0 +1,406 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Poster — a family for a one-page marketing poster: oversized type, full-
+ * bleed bands in paper, ink or one primary colour, and thin rules. A page
+ * composes `PosterShell` (its colours and font), `PosterHeader`,
+ * `PosterHero`, `PosterSwitch` (two audiences), `PosterBand`s and the blocks
+ * inside them. The presentation lives in `styles/components/poster.css`, keyed on each
+ * part's `data-slot`.
+ *
+ * The shell's `colours` and `font` brand one page without a palette: a page
+ * keeps its look whatever palette or mode the viewer picked elsewhere, and
+ * no palette picker offers it.
+ */
+interface PosterColours {
+    /** The page and light bands. Defaults to the palette's background. */
+    paper?: string;
+    /** Text, rules and dark bands. Defaults to the palette's foreground. */
+    ink?: string;
+    /** The one accent colour: primary bands, the switch, tick marks. Defaults to the palette's primary. */
+    primary?: string;
+    /** Text on the primary colour. Defaults to the palette's primary foreground. */
+    onPrimary?: string;
+    /** Quieter text: a caption, a mock-up's secondary line. Defaults to the palette's muted foreground. */
+    mute?: string;
+    /** A faint fill: a mock-up's message, its selected row. Defaults to the palette's muted. */
+    wash?: string;
+}
+interface PosterShellProps extends HTMLAttributes<HTMLDivElement> {
+    colours?: PosterColours;
+    /** A CSS font-family list. The host loads the font. Defaults to the palette's sans. */
+    font?: string;
+    /** The page's colour scheme, for form controls and scrollbars. Defaults to the document's. */
+    colorScheme?: "light" | "dark";
+}
+/** The page: its colours, font and type scale, and a cover under a notch. */
+declare const PosterShell: React.ForwardRefExoticComponent<PosterShellProps & React.RefAttributes<HTMLDivElement>>;
+/** The page's main landmark, under the header. */
+declare const PosterMain: React.ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>>;
+interface PosterBannerProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** A short label after the words, underlined ("Read why"). */
+    action?: ReactNode;
+}
+/**
+ * An announcement strip in the primary colour: one line of words and a short
+ * action, the whole strip a single link. A page puts it inside `PosterShell`,
+ * above `PosterHeader`. The space before the action keeps the two apart
+ * wherever the strip is read as plain text.
+ */
+declare const PosterBanner: React.ForwardRefExoticComponent<PosterBannerProps & React.RefAttributes<HTMLAnchorElement>>;
+interface PosterHeaderProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The wordmark: a `PosterMark`. */
+    brand: ReactNode;
+    /** The site's pages, for a site of several posters: a `PosterNav`. It sits before the action. */
+    nav?: ReactNode;
+    /** One call to action: a `PosterHeaderAction`. */
+    action?: ReactNode;
+}
+/** A sticky bar with the wordmark, the site's pages when it has several, and one call to action, ruled underneath. */
+declare const PosterHeader: React.ForwardRefExoticComponent<PosterHeaderProps & React.RefAttributes<HTMLElement>>;
+interface PosterNavProps {
+    /** The landmark's name ("Main"). */
+    label: string;
+    /** The menu button's text on a narrow screen. Defaults to "Menu". */
+    menuLabel?: string;
+    /** The pages: `PosterNavLink`s. */
+    children: ReactNode;
+}
+/**
+ * The header's pages. On a wide screen (900px and up) they sit in a row
+ * before the call to action; narrower, a Menu button opens them in a panel
+ * under the header, which a pick, Escape or a click outside closes.
+ */
+declare function PosterNav({ label, menuLabel, children }: PosterNavProps): react_jsx_runtime.JSX.Element;
+interface PosterNavLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** The page being read: marked for a screen reader (`aria-current="page"`) and underlined. */
+    current?: boolean;
+}
+/** One of the header's pages, a link. */
+declare const PosterNavLink: React.ForwardRefExoticComponent<PosterNavLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+/** The header's wordmark, a link. */
+declare const PosterMark: React.ForwardRefExoticComponent<AnchorHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>>;
+/** The header's call to action, a solid ink link. */
+declare const PosterHeaderAction: React.ForwardRefExoticComponent<AnchorHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>>;
+interface PosterHeroProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    title: ReactNode;
+    description?: ReactNode;
+    /** A small label above the title, on an inner page ("Case study"). */
+    eyebrow?: ReactNode;
+    /** home (default): a page's opening, its line set narrow; page: an inner page's opening. */
+    variant?: "home" | "page";
+    /** What the opening lets the reader do, under the line: `PosterAction`s, the first solid. */
+    actions?: ReactNode;
+}
+/** The opening statement: the page's h1 at the largest size, a line under it, and what to do next. */
+declare const PosterHero: React.ForwardRefExoticComponent<PosterHeroProps & React.RefAttributes<HTMLElement>>;
+interface PosterActionProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** solid (default): ink, like the header's call to action; quiet: an underlined label beside it. */
+    variant?: "solid" | "quiet";
+}
+/** Something to do, a link: in a hero's `actions`. */
+declare const PosterAction: React.ForwardRefExoticComponent<PosterActionProps & React.RefAttributes<HTMLAnchorElement>>;
+interface PosterSwitchOption<Value extends string> {
+    value: Value;
+    title: ReactNode;
+    hint?: ReactNode;
+}
+interface PosterSwitchProps<Value extends string> {
+    /** What the choice is, for a screen reader ("Which one is you"). */
+    label: string;
+    options: readonly PosterSwitchOption<Value>[];
+    value: Value;
+    onValueChange: (value: Value) => void;
+    className?: string;
+}
+/**
+ * Side-by-side toggle buttons that pick which half of a page shows. The
+ * pressed one fills with the primary colour from below. Each is a button
+ * with `aria-pressed`, its own tab stop.
+ */
+declare function PosterSwitch<Value extends string>({ label, options, value, onValueChange, className }: PosterSwitchProps<Value>): react_jsx_runtime.JSX.Element;
+interface PosterBandProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** paper (default), ink (a dark band) or primary (a band in the accent colour). */
+    tone?: "paper" | "ink" | "primary";
+    /** default; loose (more room, for a closing call to action); top (none below); end (a page's last band). */
+    padding?: "default" | "loose" | "top" | "end";
+    /** A small label above the title ("The trap"). */
+    eyebrow?: ReactNode;
+    /** A large line before the title. */
+    kicker?: ReactNode;
+    title?: ReactNode;
+    /** The title's size: a section's (default), the largest, or a closing band's. */
+    titleSize?: "head" | "punch" | "end";
+    /** The title's line breaks: balanced (default), or as they fall. */
+    titleWrap?: "balance" | "auto";
+    /** A large line under the title. */
+    lead?: ReactNode;
+    /** A smaller line under the title, set wider apart. */
+    description?: ReactNode;
+    /** A smaller line close under the title. */
+    after?: ReactNode;
+}
+/** A full-bleed band: an eyebrow, a title and its lines, then any blocks. */
+declare const PosterBand: React.ForwardRefExoticComponent<PosterBandProps & React.RefAttributes<HTMLElement>>;
+/** A heading inside a band, a size down from its title. */
+declare const PosterSubhead: React.ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>>;
+/** A line set apart in a band, at the middle size. */
+declare const PosterStatement: React.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+/** A calculator: its `PosterRanges`, then its `PosterFigures` and small print. */
+declare const PosterCalculator: React.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+/** Range inputs side by side (stacked on a phone). */
+declare const PosterRanges: React.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+interface PosterRangeProps {
+    label: ReactNode;
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    onValueChange: (value: number) => void;
+    /** The value as read: shown above the track and given to a screen reader ("£400,000"). */
+    valueText: string;
+    id?: string;
+}
+/** A labelled range input on a hairline track, its value shown above it. */
+declare function PosterRange({ label, value, min, max, step, onValueChange, valueText, id }: PosterRangeProps): react_jsx_runtime.JSX.Element;
+interface PosterFiguresProps extends HTMLAttributes<HTMLDivElement> {
+    items: ReadonlyArray<{
+        label: ReactNode;
+        value: ReactNode;
+    }>;
+}
+/** Big figures under a rule, each with its label: two side by side, or one across. */
+declare const PosterFigures: React.ForwardRefExoticComponent<PosterFiguresProps & React.RefAttributes<HTMLDivElement>>;
+/** The terms under a calculator. */
+declare const PosterSmallPrint: React.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+interface PosterColumnsProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * labelled: a small label over a line at the middle size; titled: a title
+     * over a paragraph; ruled: a rule, a small bold title and a line at the middle size.
+     */
+    variant?: "labelled" | "titled" | "ruled";
+    items: ReadonlyArray<{
+        heading: ReactNode;
+        text: ReactNode;
+        link?: {
+            href: string;
+            label: ReactNode;
+        };
+    }>;
+}
+/** Three columns (stacked on a phone). */
+declare const PosterColumns: React.ForwardRefExoticComponent<PosterColumnsProps & React.RefAttributes<HTMLDivElement>>;
+interface PosterTicksProps extends HTMLAttributes<HTMLUListElement> {
+    items: readonly ReactNode[];
+    /** Close under a `PosterStatement` (tight), or set apart (default). */
+    spacing?: "default" | "tight";
+}
+/** A ruled grid of short items, each marked with a square in the primary colour. */
+declare const PosterTicks: React.ForwardRefExoticComponent<PosterTicksProps & React.RefAttributes<HTMLUListElement>>;
+interface PosterDisclosureProps extends Omit<HTMLAttributes<HTMLDetailsElement>, "children"> {
+    summary: ReactNode;
+    children: ReactNode;
+    defaultOpen?: boolean;
+}
+/** A ruled disclosure: its summary with a plus that turns to a minus, and what it opens. */
+declare const PosterDisclosure: React.ForwardRefExoticComponent<PosterDisclosureProps & React.RefAttributes<HTMLDetailsElement>>;
+interface PosterFactsProps extends HTMLAttributes<HTMLDListElement> {
+    items: ReadonlyArray<{
+        term: ReactNode;
+        detail: ReactNode;
+    }>;
+}
+/** Ruled rows of a small term beside a large detail (stacked on a phone). */
+declare const PosterFacts: React.ForwardRefExoticComponent<PosterFactsProps & React.RefAttributes<HTMLDListElement>>;
+/** A paragraph after a block, at body size. */
+declare const PosterNote: React.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+interface PosterCallListProps extends HTMLAttributes<HTMLUListElement> {
+    /** What the list is, for a screen reader. */
+    label: string;
+    items: ReadonlyArray<{
+        name: ReactNode;
+        action: ReactNode;
+    }>;
+}
+/** Ruled rows of a name and a marker for what to do with it ("Call"). */
+declare const PosterCallList: React.ForwardRefExoticComponent<PosterCallListProps & React.RefAttributes<HTMLUListElement>>;
+interface PosterNumberedProps extends HTMLAttributes<HTMLOListElement> {
+    items: readonly ReactNode[];
+}
+/** Numbered steps in four columns (two on a phone), at body size. */
+declare const PosterFlow: React.ForwardRefExoticComponent<PosterNumberedProps & React.RefAttributes<HTMLOListElement>>;
+interface PosterStepsProps extends PosterNumberedProps {
+    /** three (default) ruled columns, or four (two on a narrow screen). */
+    layout?: "three" | "four";
+}
+/** Numbered steps in ruled columns (stacked on a phone), at the middle size. */
+declare const PosterSteps: React.ForwardRefExoticComponent<PosterStepsProps & React.RefAttributes<HTMLOListElement>>;
+interface PosterCostProps extends HTMLAttributes<HTMLDivElement> {
+    label: ReactNode;
+    statement: ReactNode;
+    /** Beside the statement, at its foot: a `PosterCopyText`. */
+    action?: ReactNode;
+}
+/** A ruled row: a small label over a large statement, and an action beside it. */
+declare const PosterCost: React.ForwardRefExoticComponent<PosterCostProps & React.RefAttributes<HTMLDivElement>>;
+interface PosterCopyTextProps {
+    /** What is shown and copied (an email address). */
+    text: string;
+    copyLabel?: string;
+    /** The button once the text is on the clipboard. */
+    copiedLabel?: string;
+    /** The button once the text is selected instead, where the clipboard can't be written. */
+    selectedLabel?: string;
+    /** inline (default): beside a statement; block: on its own, set apart from what comes before. */
+    placement?: "inline" | "block";
+}
+/**
+ * Text to copy, with a solid button that copies it. Where the clipboard
+ * can't be written (an insecure page, a refused permission), the text is
+ * selected instead, ready to copy by hand.
+ */
+declare function PosterCopyText({ text, copyLabel, copiedLabel, selectedLabel, placement }: PosterCopyTextProps): react_jsx_runtime.JSX.Element;
+interface PosterPeopleProps extends HTMLAttributes<HTMLUListElement> {
+    items: ReadonlyArray<{
+        name: ReactNode;
+        bio: ReactNode;
+    }>;
+}
+/** Ruled rows of a name beside a line about them (stacked on a phone). */
+declare const PosterPeople: React.ForwardRefExoticComponent<PosterPeopleProps & React.RefAttributes<HTMLUListElement>>;
+interface PosterFootnoteProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    start: ReactNode;
+    end?: ReactNode;
+}
+/** A ruled line of small print across a page's foot, at each end. */
+declare const PosterFootnote: React.ForwardRefExoticComponent<PosterFootnoteProps & React.RefAttributes<HTMLDivElement>>;
+/** A ruled link with a plus, leading to more on another page ("Open the case study"). */
+declare const PosterMoreLink: React.ForwardRefExoticComponent<AnchorHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>>;
+interface PosterNextLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** The small line above it ("Next"). */
+    label: ReactNode;
+}
+/** A large ruled link to the next page, under a small label. */
+declare const PosterNextLink: React.ForwardRefExoticComponent<PosterNextLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+/** A link inside running text, underlined. */
+declare const PosterTextLink: React.ForwardRefExoticComponent<AnchorHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>>;
+/**
+ * A line break on a wider screen only, between two sentences of a line set
+ * large, so each line ends at a sentence; each part is balanced on its own.
+ * On a phone the line wraps as it falls, as a forced break there would leave
+ * short lines. It brings its own space, for when it isn't a break.
+ */
+declare function PosterBreak(): react_jsx_runtime.JSX.Element;
+interface PosterQuoteProps {
+    children: ReactNode;
+    /** Who said it, under it. */
+    by?: ReactNode;
+    /** large (default): a band's statement; small: a quote set under other blocks. */
+    size?: "large" | "small";
+    /** A quotation (default), or a statement set as one. */
+    as?: "blockquote" | "p";
+}
+/** A quotation set large, and who said it. */
+declare function PosterQuote({ children, by, size, as }: PosterQuoteProps): react_jsx_runtime.JSX.Element;
+interface PosterStatsProps extends HTMLAttributes<HTMLDListElement> {
+    items: ReadonlyArray<{
+        value: ReactNode;
+        label: ReactNode;
+    }>;
+}
+/** Ruled figures, each over what it counts: four across, or two when there are two. */
+declare const PosterStats: React.ForwardRefExoticComponent<PosterStatsProps & React.RefAttributes<HTMLDListElement>>;
+interface PosterClaimsProps extends HTMLAttributes<HTMLUListElement> {
+    items: readonly ReactNode[];
+}
+/** Short claims, one to a line, set large. */
+declare const PosterClaims: React.ForwardRefExoticComponent<PosterClaimsProps & React.RefAttributes<HTMLUListElement>>;
+interface PosterScreenProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The product's name, at the bar's start. */
+    title: ReactNode;
+    /** What it is showing, at the bar's end. */
+    context?: ReactNode;
+}
+/** A ruled frame with a title bar: a product's screen, as a mock-up. */
+declare const PosterScreen: React.ForwardRefExoticComponent<PosterScreenProps & React.RefAttributes<HTMLDivElement>>;
+/** A screen's tabs, the first one current. */
+declare function PosterScreenTabs({ items }: {
+    items: readonly ReactNode[];
+}): react_jsx_runtime.JSX.Element;
+/** A screen in two panes (stacked on a phone): 5 to 7 (default), or 4 to 8. */
+declare function PosterScreenSplit({ ratio, children }: {
+    ratio?: "5:7" | "4:8";
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** One pane of a split screen. */
+declare function PosterScreenPane({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** A message in a mock-up chat: one sent (filled), or a question asked back (outlined). */
+declare function PosterScreenMessage({ from, children, variant }: {
+    from: ReactNode;
+    children: ReactNode;
+    variant?: "sent" | "asked";
+}): react_jsx_runtime.JSX.Element;
+/** Steps an agent is working through, each with a square. */
+declare function PosterScreenTrace({ items }: {
+    items: readonly ReactNode[];
+}): react_jsx_runtime.JSX.Element;
+/** A line leading into a pane. */
+declare function PosterScreenLead({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** A grade in a square: in the primary colour when it is a top grade. */
+declare function PosterGrade({ children, top }: {
+    children: ReactNode;
+    top?: boolean;
+}): react_jsx_runtime.JSX.Element;
+interface PosterScreenPersonProps {
+    initials: string;
+    name: ReactNode;
+    summary: ReactNode;
+    /** What is still to test about them, in a quieter line. */
+    test?: ReactNode;
+    grade: ReactNode;
+    topGrade?: boolean;
+}
+/** A person in a mock-up list: initials, name, a line, what to test, and a grade. */
+declare function PosterScreenPerson({ initials, name, summary, test, grade, topGrade }: PosterScreenPersonProps): react_jsx_runtime.JSX.Element;
+interface PosterScreenQueueProps {
+    items: ReadonlyArray<{
+        name: ReactNode;
+        role: ReactNode;
+        grade: ReactNode;
+        topGrade?: boolean;
+        selected?: boolean;
+    }>;
+}
+/** A pane of people to work through, one selected. */
+declare function PosterScreenQueue({ items }: PosterScreenQueueProps): react_jsx_runtime.JSX.Element;
+interface PosterScreenDetailProps {
+    title: ReactNode;
+    line?: ReactNode;
+    evidence?: readonly ReactNode[];
+    /** The decision's buttons as drawn: the first in the primary colour. */
+    actions?: readonly ReactNode[];
+}
+/** One person, opened: a title, a line, the evidence and the decision. */
+declare function PosterScreenDetail({ title, line, evidence, actions }: PosterScreenDetailProps): react_jsx_runtime.JSX.Element;
+interface PosterScreenRowsProps {
+    items: ReadonlyArray<{
+        name: ReactNode;
+        line: ReactNode;
+        grade: ReactNode;
+        topGrade?: boolean;
+        action: ReactNode;
+        needsYou?: boolean;
+    }>;
+}
+/** Rows of people with a line, a grade and what to do: filled, or outlined when it needs a person. */
+declare function PosterScreenRows({ items }: PosterScreenRowsProps): react_jsx_runtime.JSX.Element;
+/** A quiet line under a mock-up. */
+declare const PosterMockNote: React.ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+
+export { PosterAction, type PosterActionProps, PosterBand, type PosterBandProps, PosterBanner, type PosterBannerProps, PosterBreak, PosterCalculator, PosterCallList, type PosterCallListProps, PosterClaims, type PosterClaimsProps, type PosterColours, PosterColumns, type PosterColumnsProps, PosterCopyText, type PosterCopyTextProps, PosterCost, type PosterCostProps, PosterDisclosure, type PosterDisclosureProps, PosterFacts, type PosterFactsProps, PosterFigures, type PosterFiguresProps, PosterFlow, PosterFootnote, type PosterFootnoteProps, PosterGrade, PosterHeader, PosterHeaderAction, type PosterHeaderProps, PosterHero, type PosterHeroProps, PosterMain, PosterMark, PosterMockNote, PosterMoreLink, PosterNav, PosterNavLink, type PosterNavLinkProps, type PosterNavProps, PosterNextLink, type PosterNextLinkProps, PosterNote, type PosterNumberedProps, PosterPeople, type PosterPeopleProps, PosterQuote, type PosterQuoteProps, PosterRange, type PosterRangeProps, PosterRanges, PosterScreen, PosterScreenDetail, type PosterScreenDetailProps, PosterScreenLead, PosterScreenMessage, PosterScreenPane, PosterScreenPerson, type PosterScreenPersonProps, type PosterScreenProps, PosterScreenQueue, type PosterScreenQueueProps, PosterScreenRows, type PosterScreenRowsProps, PosterScreenSplit, PosterScreenTabs, PosterScreenTrace, PosterShell, type PosterShellProps, PosterSmallPrint, PosterStatement, PosterStats, type PosterStatsProps, PosterSteps, type PosterStepsProps, PosterSubhead, PosterSwitch, type PosterSwitchOption, type PosterSwitchProps, PosterTextLink, PosterTicks, type PosterTicksProps };