trc-ui 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode, ElementType, Ref, SVGProps } from 'react';
+
+/** Joins CSS class names, skipping empty values. */
+declare function cx(...classes: (string | false | null | undefined)[]): string;
+
+/**
+ * Colors the words between asterisks with the accent: "How it *works*".
+ * Without asterisks, `accentLast` colors the last words (titles coming from a CMS).
+ */
+declare function AccentText({ text, accentLast }: {
+    text: string;
+    accentLast?: number;
+}): react.JSX.Element;
+/** Plain text of a marked-up title, for attributes (`alt`, `title`, metadata). */
+declare const plainText: (text: string) => string;
+type HeadingSize = "display" | "xl" | "lg" | "md" | "sm";
+type HeadingProps = Omit<ComponentPropsWithoutRef<"h2">, "children"> & {
+    /** Rendered tag; the visual size is set separately with `size`. */
+    as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+    size?: HeadingSize;
+    /** When `children` is a string without asterisks, number of trailing words in the accent color. */
+    accentLast?: number;
+    children: ReactNode;
+};
+/** Thin Montserrat 400 heading; a string may contain an *accent word* between asterisks. */
+declare function Heading({ as: Tag, size, accentLast, className, children, ...props }: HeadingProps): react.JSX.Element;
+type TextProps<C extends ElementType = "p"> = {
+    as?: C;
+    size?: "lg" | "md" | "sm";
+    tone?: "default" | "muted" | "subtle";
+} & Omit<ComponentPropsWithoutRef<C>, "as" | "size">;
+/** Body text; `tone="muted"` (default) so that it does not compete with headings. */
+declare function Text<C extends ElementType = "p">({ as, size, tone, className, ...props }: TextProps<C>): react.JSX.Element;
+/** Large thin number in the accent color ("01", "02"…), reserved for steps in a real order. */
+declare function StepNumber({ n, size, className }: {
+    n: number;
+    size?: "md" | "sm";
+    className?: string;
+}): react.JSX.Element;
+
+type PillStyle = {
+    /** White background: the main action of a screen. */
+    solid?: boolean;
+    /** Compact version (header, toolbars). */
+    size?: "md" | "sm";
+    /** Replaces the dot's arrow (for instance a left arrow for "Back"). */
+    icon?: ReactNode;
+};
+type PillButtonProps = ComponentPropsWithoutRef<"button"> & PillStyle & {
+    /** Replaces the icon with a spinner and disables the button. */
+    loading?: boolean;
+};
+/** Pill button: thin border, accent dot with an arrow that stretches on hover. */
+declare const PillButton: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & PillStyle & {
+    /** Replaces the icon with a spinner and disables the button. */
+    loading?: boolean;
+} & react.RefAttributes<HTMLButtonElement>>;
+type PillLinkProps<C extends ElementType = "a"> = PillStyle & {
+    /** Router link component (Next.js or React Router `Link`…); `<a>` by default. */
+    as?: C;
+} & Omit<ComponentPropsWithoutRef<C>, "as" | keyof PillStyle>;
+/** Same pill as a link. With a router: `<PillLink as={Link} href="/">`. */
+declare const PillLink: <C extends ElementType = "a">(props: PillLinkProps<C> & {
+    ref?: Ref<HTMLAnchorElement>;
+}) => ReactNode;
+
+type IconProps = SVGProps<SVGSVGElement>;
+declare const ArrowRight: (props: IconProps) => react.JSX.Element;
+declare const ArrowLeft: (props: IconProps) => react.JSX.Element;
+declare const ChevronDown: (props: IconProps) => react.JSX.Element;
+declare const Check: (props: IconProps) => react.JSX.Element;
+declare const Menu: (props: IconProps) => react.JSX.Element;
+declare const Close: (props: IconProps) => react.JSX.Element;
+declare const ArrowUp: (props: IconProps) => react.JSX.Element;
+
+type Polymorphic<C extends ElementType, P> = P & {
+    as?: C;
+} & Omit<ComponentPropsWithoutRef<C>, "as" | keyof P>;
+type ContainerProps<C extends ElementType = "div"> = Polymorphic<C, {
+    /** `default`: 1280 px, for text and grids; `wide`: 1600 px, for full-width cards; `narrow`: 768 px. */
+    size?: "default" | "wide" | "narrow";
+}>;
+/** Centered max width, with side gutters that grow with the screen. */
+declare function Container<C extends ElementType = "div">({ as, size, className, ...props }: ContainerProps<C>): react.JSX.Element;
+type SectionProps<C extends ElementType = "section"> = Polymorphic<C, {
+    /** Vertical spacing. */
+    spacing?: "sm" | "md" | "lg" | "none";
+    /**
+     * Card inset from the screen edges ("magazine" effect): graphite background and rounded corners,
+     * for banners, calls to action and heroes.
+     */
+    inset?: boolean;
+}>;
+/** Vertical block of a page. With `inset`, it becomes a large rounded card a few pixels from the edges. */
+declare function Section<C extends ElementType = "section">({ as, spacing, inset, className, children, ...props }: SectionProps<C>): react.JSX.Element;
+type CardProps<C extends ElementType = "div"> = Polymorphic<C, {
+    /** `alt`: a slightly lighter grey, to tell two side-by-side blocks apart. */
+    tone?: "default" | "alt";
+    padding?: "none" | "sm" | "md" | "lg";
+    /** Lightens on hover (clickable cards: links, buttons). */
+    interactive?: boolean;
+    /** Decorative watermark icon: very large, thin stroke, half out of the corner; wakes up on hover. */
+    watermark?: ReactNode;
+}>;
+/** Graphite card, rounded corners, no shadow: depth comes from shades of grey. */
+declare function Card<C extends ElementType = "div">({ as, tone, padding, interactive, watermark, className, children, ...props }: CardProps<C>): react.JSX.Element;
+
+type FieldProps = {
+    label: ReactNode;
+    /** Hint shown under the control. */
+    hint?: ReactNode;
+    /** Error message: replaces the hint and marks the control as invalid. */
+    error?: ReactNode;
+    required?: boolean;
+    /** Control id; generated when omitted. */
+    id?: string;
+    className?: string;
+    children: ReactNode;
+};
+/**
+ * Label, hint and error of a form control. The control placed inside (`Input`, `Textarea`, `Select`)
+ * automatically receives its `id`, `aria-describedby` and `aria-invalid`.
+ */
+declare function Field({ label, hint, error, required, id, className, children }: FieldProps): react.JSX.Element;
+type ControlProps = {
+    invalid?: boolean;
+};
+type InputProps = ComponentPropsWithoutRef<"input"> & ControlProps;
+declare const Input: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & ControlProps & react.RefAttributes<HTMLInputElement>>;
+type TextareaProps = ComponentPropsWithoutRef<"textarea"> & ControlProps;
+declare const Textarea: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, "ref"> & ControlProps & react.RefAttributes<HTMLTextAreaElement>>;
+type SelectProps = ComponentPropsWithoutRef<"select"> & ControlProps & {
+    /** Empty option shown until something is chosen. */
+    placeholder?: string;
+};
+/** Native select (accessible and mobile friendly), dressed with a thin chevron. */
+declare const Select: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.SelectHTMLAttributes<HTMLSelectElement>, HTMLSelectElement>, "ref"> & ControlProps & {
+    /** Empty option shown until something is chosen. */
+    placeholder?: string;
+} & react.RefAttributes<HTMLSelectElement>>;
+
+type ToggleProps = Omit<ComponentPropsWithoutRef<"input">, "type"> & {
+    label: ReactNode;
+    /** Extra detail under the label. */
+    description?: ReactNode;
+};
+type CheckboxProps = ToggleProps;
+/** Native checkbox, filled with the accent color once checked. */
+declare const Checkbox: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "type"> & {
+    label: ReactNode;
+    /** Extra detail under the label. */
+    description?: ReactNode;
+} & react.RefAttributes<HTMLInputElement>>;
+type SwitchProps = ToggleProps;
+/** Switch: a native checkbox announced as a `switch` to screen readers. */
+declare const Switch: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "type"> & {
+    label: ReactNode;
+    /** Extra detail under the label. */
+    description?: ReactNode;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type NavLink = {
+    label: ReactNode;
+    href: string;
+    /** Current page: marked with an accent dot. */
+    active?: boolean;
+};
+type NavMenu = {
+    label: ReactNode;
+    /** Dropdown items, with an optional short description (no numbers). */
+    items: (NavLink & {
+        description?: ReactNode;
+    })[];
+};
+type NavItem = NavLink | NavMenu;
+type SiteHeaderProps = {
+    /** Logo (white), wrapped in a link to `homeHref`. */
+    logo: ReactNode;
+    /** Accessible name of the logo link, usually the brand name. */
+    logoLabel: string;
+    homeHref?: string;
+    nav?: NavItem[];
+    /** Main action, shown as a compact pill (and a large one in the mobile menu). */
+    cta?: {
+        label: ReactNode;
+        href: string;
+    };
+    /** Extra elements on the right on large screens (language switcher…). */
+    actions?: ReactNode;
+    /** Content added at the bottom of the mobile menu. */
+    mobileFooter?: ReactNode;
+    /** Router link component (Next.js `Link`…); `<a>` by default. */
+    linkAs?: ElementType;
+    /** Scroll offset (px) from which the bar becomes blurred graphite. */
+    scrollThreshold?: number;
+    menuLabel?: string;
+    closeLabel?: string;
+    className?: string;
+};
+/**
+ * Floating header: transparent over the hero at the top of the page, it becomes a blurred
+ * graphite bar as soon as the page scrolls. Dropdowns on large screens, side panel on mobile.
+ */
+declare function SiteHeader({ logo, logoLabel, homeHref, nav, cta, actions, mobileFooter, linkAs: LinkTag, scrollThreshold, menuLabel, closeLabel, className, }: SiteHeaderProps): react.JSX.Element;
+
+type FooterLink = {
+    label: ReactNode;
+    href: string;
+};
+type SiteFooterProps = {
+    /** Logo (white), wrapped in a link to `homeHref`. */
+    logo?: ReactNode;
+    logoLabel?: string;
+    homeHref?: string;
+    /** Short sentence under the logo. */
+    tagline?: ReactNode;
+    /** Under the sentence: a pill, a contact… */
+    children?: ReactNode;
+    /** Site map in columns, each with a spaced small-caps title. */
+    columns?: {
+        title: ReactNode;
+        links: FooterLink[];
+    }[];
+    /** Accessible name of the site map. */
+    columnsLabel?: string;
+    /** Bottom line (copyright, credits…). */
+    copyright?: ReactNode;
+    /** Legal links, aligned right on large screens. */
+    legal?: FooterLink[];
+    legalLabel?: string;
+    /** Router link component (Next.js `Link`…); `<a>` by default. */
+    linkAs?: ElementType;
+    className?: string;
+};
+/** Graphite card footer: brand and call to action, site map in columns, legal links. */
+declare function SiteFooter({ logo, logoLabel, homeHref, tagline, children, columns, columnsLabel, copyright, legal, legalLabel, linkAs: LinkTag, className, }: SiteFooterProps): react.JSX.Element;
+
+type PageHeroProps = {
+    /** Title; the words between *asterisks* take the accent, otherwise the last words (`accentLast`). */
+    title: string;
+    /** Number of trailing words in the accent color when the title has no asterisks (2 for a long title, 1 otherwise). */
+    accentLast?: number;
+    description?: ReactNode;
+    /** Discreet line under the description (last updated date, breadcrumb…). */
+    meta?: ReactNode;
+    /**
+     * Background photo, heavily darkened: a URL, or a ready-made element (Next.js `<Image fill />`…).
+     * Without a photo, a subtle accent glow on a graphite background.
+     */
+    image?: string | ReactNode;
+    /** Photo position (`object-position`). */
+    imagePosition?: string;
+    /** Content under the text (pills…). */
+    children?: ReactNode;
+    className?: string;
+};
+/**
+ * Header of inner pages: rounded card inset from the edges, darkened background photo,
+ * thin title whose last words take the accent. Leaves room for the floating header above.
+ */
+declare function PageHero({ title, accentLast, description, meta, image, imagePosition, children, className, }: PageHeroProps): react.JSX.Element;
+type HeroClip = {
+    /** Muted video, 1280 px, without an audio track. Provide WebM and/or MP4. */
+    webm?: string;
+    mp4?: string;
+    /** Image shown before playback, and alone when the user prefers reduced motion. */
+    poster?: string;
+};
+type HeroVideoProps = {
+    /** Videos played one after another with a crossfade; the first one is picked at random. */
+    clips: HeroClip[];
+    /** Hero text (title, description, pills), pinned to the bottom left. */
+    children: ReactNode;
+    /** Optional block pinned to the bottom right on large screens. */
+    aside?: ReactNode;
+    /** Crossfade duration, in seconds. */
+    fade?: number;
+    /** Soft parallax: the video moves down slower than the page. */
+    parallax?: boolean;
+    className?: string;
+};
+/**
+ * Home page hero: rounded card inset from the edges, muted background videos that alternate with
+ * a crossfade, dark veils for legibility. No video in the server render: the pick happens
+ * after hydration, then the video fades in. Reduced motion: the still image only.
+ */
+declare function HeroVideo({ clips, children, aside, fade, parallax, className }: HeroVideoProps): react.JSX.Element;
+
+type BackToTopProps = {
+    label?: string;
+    /** Scroll offset, in viewport heights, from which the button appears. */
+    threshold?: number;
+    className?: string;
+};
+/** Floating accent "Back to top" button: appears once the first screen is scrolled past. */
+declare function BackToTop({ label, threshold, className }: BackToTopProps): react.JSX.Element;
+
+export { AccentText, ArrowLeft, ArrowRight, ArrowUp, BackToTop, Card, Check, Checkbox, ChevronDown, Close, Container, Field, Heading, HeroVideo, Input, Menu, PageHero, PillButton, PillLink, Section, Select, SiteFooter, SiteHeader, StepNumber, Switch, Text, Textarea, cx, plainText };
+export type { BackToTopProps, CardProps, CheckboxProps, ContainerProps, FieldProps, FooterLink, HeadingProps, HeadingSize, HeroClip, HeroVideoProps, InputProps, NavItem, NavLink, NavMenu, PageHeroProps, PillButtonProps, PillLinkProps, SectionProps, SelectProps, SiteFooterProps, SiteHeaderProps, SwitchProps, TextProps, TextareaProps };