trc-ui 0.0.0-stage → 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,1021 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode, ElementType, Ref, SVGProps, ReactElement, KeyboardEvent } 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;
+declare const Calendar: (props: IconProps) => react.JSX.Element;
+declare const ChevronLeft: (props: IconProps) => react.JSX.Element;
+declare const ChevronRight: (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;
+
+type DialogProps = {
+    open: boolean;
+    /** Called on Escape, on the close button and on the overlay. */
+    onClose: () => void;
+    /** Title of the window, also its accessible name. */
+    title: ReactNode;
+    /** Short text under the title, announced with it. */
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Actions at the bottom, usually pills: the main one solid, on the right. */
+    footer?: ReactNode;
+    size?: "sm" | "md" | "lg";
+    closeLabel?: string;
+    closeOnOverlay?: boolean;
+    className?: string;
+};
+/**
+ * Modal window: a graphite card centered over a dark overlay. Focus moves inside and stays there;
+ * Escape, the close button or the overlay close it, and focus returns to where it was.
+ * Put `data-autofocus` on the element that should receive focus first.
+ */
+declare function Dialog({ size, closeLabel, closeOnOverlay, className, ...props }: DialogProps): react.JSX.Element;
+
+type DrawerProps = {
+    open: boolean;
+    onClose: () => void;
+    title: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Actions pinned to the bottom of the panel. */
+    footer?: ReactNode;
+    /** Edge the panel slides from. */
+    side?: "right" | "left";
+    size?: "sm" | "md";
+    closeLabel?: string;
+    closeOnOverlay?: boolean;
+    className?: string;
+};
+/** Side panel that slides over the page: filters, cart, settings, mobile navigation. Modal, like `Dialog`. */
+declare function Drawer({ side, size, closeLabel, closeOnOverlay, className, ...props }: DrawerProps): react.JSX.Element;
+
+type Side = "top" | "bottom";
+type Align = "start" | "center" | "end";
+
+type MenuAction = {
+    label: ReactNode;
+    /** Called when the item is chosen with a click, Enter or Space. */
+    onSelect?: () => void;
+    /** Turns the item into a link. */
+    href?: string;
+    /** Hint shown on the right, such as a keyboard shortcut. */
+    hint?: ReactNode;
+    disabled?: boolean;
+    /** Destructive action (delete, leave…), in the error color. */
+    danger?: boolean;
+    /** Text used for typeahead when the label is not a string. */
+    textValue?: string;
+};
+type MenuItem = MenuAction | "separator";
+type TriggerProps$1 = {
+    ref?: Ref<HTMLElement>;
+    id?: string;
+    onClick?: (e: unknown) => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+};
+type DropdownMenuProps = {
+    /** Element that opens the menu, usually a pill or an icon button. */
+    trigger: ReactElement<TriggerProps$1>;
+    items: MenuItem[];
+    align?: Align;
+    /** Link component of your router, for items with an `href`. */
+    linkAs?: ElementType;
+    className?: string;
+};
+/**
+ * Menu of actions opened from a trigger. Keyboard: Enter, Space or the arrows open it; the arrows,
+ * Home and End move between items; typing a letter jumps to the next item starting with it;
+ * Escape closes and returns focus to the trigger; Tab closes and moves on.
+ */
+declare function DropdownMenu({ trigger, items, align, linkAs: LinkTag, className }: DropdownMenuProps): react.JSX.Element;
+
+type TriggerProps = {
+    ref?: Ref<HTMLElement>;
+    onClick?: (e: unknown) => void;
+};
+type PopoverProps = {
+    /** Element that opens the panel. */
+    trigger: ReactElement<TriggerProps>;
+    /** Title of the panel, also its accessible name. */
+    title?: ReactNode;
+    /** Accessible name when there is no visible title. */
+    label?: string;
+    children: ReactNode;
+    side?: Side;
+    align?: Align;
+    /** Controlled state; leave out to let the popover manage itself. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+};
+/**
+ * Floating panel anchored to a trigger, for short content and small forms. Not modal: the page stays
+ * usable. Focus moves into the panel when it opens; Escape or a click outside closes it.
+ */
+declare function Popover({ trigger, title, label, children, side, align, open: controlled, onOpenChange, className, }: PopoverProps): react.JSX.Element;
+
+type ChildProps = {
+    ref?: Ref<HTMLElement>;
+    "aria-describedby"?: string;
+    onMouseEnter?: (e: unknown) => void;
+    onMouseLeave?: (e: unknown) => void;
+    onFocus?: (e: unknown) => void;
+    onBlur?: (e: unknown) => void;
+};
+type TooltipProps = {
+    /** Short text describing the element; never the only way to get the information. */
+    label: ReactNode;
+    /** A single focusable element: a button, a link, an input. */
+    children: ReactElement<ChildProps>;
+    side?: Side;
+    /** Delay before showing on hover, in milliseconds. Keyboard focus shows it right away. */
+    delay?: number;
+    className?: string;
+};
+/**
+ * Small label shown on hover and keyboard focus, tied to its element with `aria-describedby`.
+ * It stays open while the pointer moves onto it, and Escape hides it (WCAG 1.4.13).
+ */
+declare function Tooltip({ label, children, side, delay, className }: TooltipProps): react.JSX.Element;
+
+type ToastTone = "default" | "success" | "error";
+type ToastOptions = {
+    description?: ReactNode;
+    tone?: ToastTone;
+    /** Time on screen in milliseconds; `Infinity` keeps it until dismissed. */
+    duration?: number;
+    /** One action, such as "Undo"; choosing it also dismisses the toast. */
+    action?: {
+        label: ReactNode;
+        onClick: () => void;
+    };
+};
+/**
+ * Shows a short message in the `<Toaster />`. Returns its id, for `toast.dismiss(id)`.
+ * `toast.success()` and `toast.error()` set the tone.
+ */
+declare function toast(title: ReactNode, options?: ToastOptions): number;
+declare namespace toast {
+    var success: (title: ReactNode, options?: Omit<ToastOptions, "tone">) => number;
+    var error: (title: ReactNode, options?: Omit<ToastOptions, "tone">) => number;
+    var dismiss: (id?: number) => void;
+}
+type ToasterProps = {
+    position?: "bottom-right" | "bottom-center" | "top-right";
+    /** Default time on screen, in milliseconds. */
+    duration?: number;
+    /** Accessible name of the notification area. */
+    label?: string;
+    closeLabel?: string;
+};
+/**
+ * Notification area, placed once near the root of the app. New toasts are announced to screen
+ * readers (errors right away); timers pause while the pointer or the keyboard focus is inside.
+ */
+declare function Toaster({ position, duration, label, closeLabel, }: ToasterProps): react.JSX.Element;
+
+type AlertProps = Omit<ComponentPropsWithoutRef<"div">, "title"> & {
+    title?: ReactNode;
+    /** `info` and `success` use the accent, `error` the error color. */
+    tone?: "info" | "success" | "error";
+    /** Actions under the text, such as a small pill. */
+    actions?: ReactNode;
+};
+/**
+ * Inline message in a graphite card, marked by a thin colored edge rather than an icon badge.
+ * Static by default; pass `role="alert"` (urgent) or `role="status"` when it appears after an action.
+ */
+declare function Alert({ title, tone, actions, className, children, ...props }: AlertProps): react.JSX.Element;
+
+type TabItem = {
+    value: string;
+    label: ReactNode;
+    content: ReactNode;
+    disabled?: boolean;
+};
+type TabsProps = {
+    items: TabItem[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Accessible name of the tab list. */
+    label?: string;
+    /**
+     * `automatic`: the arrows select the tab they move to. `manual`: they only move the focus,
+     * Enter or Space selects (for panels that are slow to render).
+     */
+    activation?: "automatic" | "manual";
+    className?: string;
+};
+/**
+ * Tabs: thin labels, the selected one underlined with the accent. Keyboard: Left and Right arrows,
+ * Home and End; only the selected tab is in the Tab order (roving tabindex).
+ */
+declare function Tabs({ items, value, defaultValue, onValueChange, label, activation, className, }: TabsProps): react.JSX.Element;
+
+type SegmentedOption = {
+    value: string;
+    label: ReactNode;
+    disabled?: boolean;
+};
+type SegmentedControlProps = {
+    options: SegmentedOption[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Accessible name of the group. */
+    label: string;
+    /** Form field name; generated when omitted. */
+    name?: string;
+    size?: "md" | "sm";
+    className?: string;
+};
+/**
+ * Pill switch between a few options, built on native radio buttons: the arrows move the choice,
+ * forms and screen readers work as usual. For views of the same content; use Tabs to switch panels.
+ */
+declare function SegmentedControl({ options, value, defaultValue, onValueChange, label, name, size, className, }: SegmentedControlProps): react.JSX.Element;
+
+type AccordionItem = {
+    value: string;
+    title: ReactNode;
+    content: ReactNode;
+    disabled?: boolean;
+};
+type AccordionProps = {
+    items: AccordionItem[];
+    /** `single`: one item open at a time. `multiple`: any number. */
+    type?: "single" | "multiple";
+    /** Open items. */
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    /** Level of the heading wrapping each button, to fit the page outline. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    className?: string;
+};
+/**
+ * Items that open and close, for FAQs and details. Each title is a button inside a heading; the
+ * height animates; closed content is out of the accessibility tree. Up and Down arrows, Home and
+ * End move between titles.
+ */
+declare function Accordion({ items, type, value, defaultValue, onValueChange, headingLevel, className, }: AccordionProps): react.JSX.Element;
+
+type StepItem = {
+    title: ReactNode;
+    description?: ReactNode;
+};
+type StepsProps = {
+    items: StepItem[];
+    /**
+     * Index of the step in progress (from 0): earlier steps are complete, later ones upcoming.
+     * Leave out for a plain list of steps, all alike.
+     */
+    current?: number;
+    className?: string;
+};
+/**
+ * Vertical timeline of steps in a real order: large thin numbers in the accent, joined by a hairline.
+ * With `current`, the step in progress carries `aria-current="step"` and the upcoming ones fade.
+ */
+declare function Steps({ items, current, className }: StepsProps): react.JSX.Element;
+
+type BreadcrumbItem = {
+    label: ReactNode;
+    href?: string;
+};
+type BreadcrumbsProps = {
+    /** From the home page to the current page; the last item is the current page and has no link. */
+    items: BreadcrumbItem[];
+    label?: string;
+    linkAs?: ElementType;
+    className?: string;
+};
+/** Trail from the home page to the current page, separated by thin slashes. */
+declare function Breadcrumbs({ items, label, linkAs: LinkTag, className }: BreadcrumbsProps): react.JSX.Element;
+
+type Entry = number | "ellipsis";
+/**
+ * Pages to show: always the first and the last, the current one with `siblings` on each side, and
+ * ellipses in between. The number of entries stays constant, so the controls do not jump around.
+ */
+declare function paginationRange(page: number, total: number, siblings?: number): Entry[];
+type PaginationProps = {
+    /** Current page, from 1. */
+    page: number;
+    /** Number of pages. */
+    total: number;
+    /** Buttons mode: called with the new page. */
+    onPageChange?: (page: number) => void;
+    /**
+     * Links mode (better for search engines): the address of each page, as a function or as a
+     * pattern with `{page}`, such as `"/blog/page/{page}"`. The pattern also works from a server component.
+     */
+    href?: string | ((page: number) => string);
+    siblings?: number;
+    linkAs?: ElementType;
+    label?: string;
+    previousLabel?: string;
+    nextLabel?: string;
+    /** Accessible name of a page number: a template such as "Page {page}", or a function. */
+    pageLabel?: string | ((page: number) => string);
+    className?: string;
+};
+/** Page navigation: numbers with ellipses, previous and next. As buttons or as links. */
+declare function Pagination({ page, total, onPageChange, href, siblings, linkAs: LinkTag, label, previousLabel, nextLabel, pageLabel, className, }: PaginationProps): react.JSX.Element | null;
+
+type Language = {
+    /** Language code, shown in capitals: "en", "fr"… */
+    code: string;
+    /** Full name in that language ("English", "Français"), for screen readers. */
+    name: string;
+    /** Same page in that language; without it, the switch calls `onChange`. */
+    href?: string;
+};
+type LanguageSwitcherProps = {
+    languages: Language[];
+    /** Code of the current language. */
+    value: string;
+    onChange?: (code: string) => void;
+    label?: string;
+    linkAs?: ElementType;
+    className?: string;
+};
+/** EN | FR pill: links to the same page in each language (or buttons), the current one in the accent. */
+declare function LanguageSwitcher({ languages, value, onChange, label, linkAs: LinkTag, className, }: LanguageSwitcherProps): react.JSX.Element;
+
+type RadioOption = {
+    value: string;
+    label: ReactNode;
+    description?: ReactNode;
+    disabled?: boolean;
+};
+type RadioGroupProps = {
+    /** Question of the group, rendered as its legend. */
+    label: ReactNode;
+    options: RadioOption[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    name?: string;
+    hint?: ReactNode;
+    error?: ReactNode;
+    required?: boolean;
+    orientation?: "vertical" | "horizontal";
+    className?: string;
+};
+/**
+ * A choice among a few options, as native radio buttons in a fieldset: the legend is read with
+ * each option, the arrows move the choice, and the hint or error is tied to the group.
+ */
+declare function RadioGroup({ label, options, value, defaultValue, onValueChange, name, hint, error, required, orientation, className, }: RadioGroupProps): react.JSX.Element;
+
+type PasswordInputProps = Omit<InputProps, "type"> & {
+    /** Visible text of the button: "Show", "Afficher"… */
+    showLabel?: string;
+    hideLabel?: string;
+    /** Completes the button's name for screen readers: "Show password". */
+    noun?: string;
+};
+/**
+ * Password field with a Show / Hide button. Works inside `Field` like `Input`. The button's
+ * accessible name includes its visible text ("Show password"), as WCAG 2.5.3 asks.
+ */
+declare const PasswordInput: react.ForwardRefExoticComponent<Omit<InputProps, "type"> & {
+    /** Visible text of the button: "Show", "Afficher"… */
+    showLabel?: string;
+    hideLabel?: string;
+    /** Completes the button's name for screen readers: "Show password". */
+    noun?: string;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type PinInputProps = {
+    /** Number of characters. */
+    length?: number;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Called once every box is filled. */
+    onComplete?: (value: string) => void;
+    /** `numeric` opens the number keyboard on phones and accepts digits only. */
+    type?: "numeric" | "alphanumeric";
+    /** Hides the characters, like a password. */
+    mask?: boolean;
+    /** Accessible name of the group: "Verification code". */
+    label?: string;
+    /**
+     * Accessible name of each box: a template such as "Character {index} of {length}" ({index} starts
+     * at 1), or a function receiving the 0-based index.
+     */
+    charLabel?: string | ((index: number, length: number) => string);
+    invalid?: boolean;
+    disabled?: boolean;
+    id?: string;
+    name?: string;
+    className?: string;
+};
+/**
+ * One box per character for one-time codes. Typing moves forward, Backspace moves back, pasting a code
+ * fills every box, and phones can fill it from a text message (`autocomplete="one-time-code"`).
+ * Inside a `Field`, the label focuses the first box and the hint or error describes the group.
+ */
+declare function PinInput({ length, value, defaultValue, onChange, onComplete, type, mask, label, charLabel, invalid, disabled, id, name, className, }: PinInputProps): react.JSX.Element;
+
+type ComboboxOption = {
+    value: string;
+    label: string;
+    description?: ReactNode;
+    disabled?: boolean;
+};
+type ComboboxProps = {
+    options: ComboboxOption[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+    placeholder?: string;
+    /** Shown when nothing matches the search. */
+    emptyText?: ReactNode;
+    invalid?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    id?: string;
+    /** Form field name: the chosen value is submitted. */
+    name?: string;
+    className?: string;
+};
+/**
+ * Search field with a list of suggestions. Typing filters (ignoring case and accents); the arrows
+ * move the active option while focus stays in the field; Enter chooses; Escape closes; leaving the
+ * field restores the chosen label. Works inside `Field` like `Input`.
+ */
+declare function Combobox({ options, value, defaultValue, onValueChange, placeholder, emptyText, invalid, disabled, required, id, name, className, }: ComboboxProps): react.JSX.Element;
+
+/** Readable size: 820 B, 14.2 KB, 3.5 MB. */
+declare function formatBytes(bytes: number): string;
+/** Whether a file matches an `accept` list such as "image/*,.pdf". */
+declare function acceptsFile(file: File, accept?: string): boolean;
+type FileRejection = {
+    file: File;
+    reason: "type" | "size" | "count";
+};
+type Rules = {
+    accept?: string;
+    maxSize?: number;
+    maxFiles?: number;
+};
+/** Splits files into accepted and rejected ones, with the reason of each rejection. */
+declare function validateFiles(files: File[], { accept, maxSize, maxFiles }: Rules, alreadyAccepted?: number): {
+    accepted: File[];
+    rejected: FileRejection[];
+};
+type FileInputProps = Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "onChange"> & {
+    onFilesChange?: (files: File[]) => void;
+    buttonLabel?: string;
+    placeholder?: string;
+    /** Text when several files are chosen: a template such as "{count} files", or a function. */
+    countLabel?: string | ((count: number) => string);
+    invalid?: boolean;
+};
+/**
+ * Compact file field: a "Choose a file" button and the chosen names, on the native file input
+ * (hidden but focusable). Works inside `Field` like `Input`.
+ */
+declare const FileInput: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "type" | "value" | "defaultValue" | "onChange"> & {
+    onFilesChange?: (files: File[]) => void;
+    buttonLabel?: string;
+    placeholder?: string;
+    /** Text when several files are chosen: a template such as "{count} files", or a function. */
+    countLabel?: string | ((count: number) => string);
+    invalid?: boolean;
+} & react.RefAttributes<HTMLInputElement>>;
+type DropzoneProps = Rules & {
+    multiple?: boolean;
+    /** Called with every accepted file after each change. */
+    onFilesChange?: (files: File[]) => void;
+    /** Main text: "Drop files here or". */
+    title?: ReactNode;
+    /** Link-looking word that opens the file picker: "browse". */
+    browseLabel?: ReactNode;
+    /** Constraints shown under the title: "PNG or PDF, up to 5 MB". */
+    hint?: ReactNode;
+    /** Name of the remove button: a template such as "Remove {name}", or a function. */
+    removeLabel?: string | ((file: File) => string);
+    /**
+     * Message of a rejected file: one template per reason, with {name}, or a function.
+     */
+    rejectionLabel?: Partial<Record<FileRejection["reason"], string>> | ((rejection: FileRejection) => string);
+    name?: string;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+};
+/**
+ * Area to drop files on, or to click (and reach with the keyboard) to browse. Accepted files are
+ * listed with their size and a remove button; rejected ones are announced with their reason.
+ */
+declare function Dropzone({ accept, maxSize, maxFiles, multiple, onFilesChange, title, browseLabel, hint, removeLabel, rejectionLabel, name, disabled, id, className, }: DropzoneProps): react.JSX.Element;
+
+type SliderProps = Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "onChange"> & {
+    value?: number;
+    defaultValue?: number;
+    onValueChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Shows the value next to the slider. */
+    showValue?: boolean;
+    /** Formats the shown and announced value: "€ 40", "75 %". */
+    formatValue?: (value: number) => ReactNode;
+    invalid?: boolean;
+};
+/**
+ * Range slider on the native input: keyboard (arrows, Page Up / Down, Home, End) and screen readers
+ * work as usual. The track fills with the accent up to the thumb. Works inside `Field` like `Input`.
+ */
+declare const Slider: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "type" | "value" | "defaultValue" | "onChange"> & {
+    value?: number;
+    defaultValue?: number;
+    onValueChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Shows the value next to the slider. */
+    showValue?: boolean;
+    /** Formats the shown and announced value: "€ 40", "75 %". */
+    formatValue?: (value: number) => ReactNode;
+    invalid?: boolean;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type DatePickerProps = {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onValueChange?: (date: Date | null) => void;
+    /** Earliest and latest choosable dates. */
+    min?: Date;
+    max?: Date;
+    /** Locale of the month and day names, such as "fr-FR"; the browser's by default. */
+    locale?: string;
+    /** First day of the week: 0 for Sunday, 1 for Monday. */
+    weekStartsOn?: number;
+    placeholder?: string;
+    /** Formats the chosen date in the field. */
+    formatDate?: (date: Date) => string;
+    /** Form field name: the date is submitted as YYYY-MM-DD. */
+    name?: string;
+    label?: string;
+    previousMonthLabel?: string;
+    nextMonthLabel?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    id?: string;
+    className?: string;
+};
+/**
+ * Date field that opens a calendar. Keyboard in the calendar: arrows move by a day or a week, Home
+ * and End to the start and end of the week, Page Up and Page Down by a month (with Shift, a year),
+ * Enter or Space chooses, Escape closes. Each day is announced in full; works inside `Field`.
+ */
+declare function DatePicker({ value, defaultValue, onValueChange, min, max, locale, weekStartsOn, placeholder, formatDate, name, label, previousMonthLabel, nextMonthLabel, invalid, disabled, required, id, className, }: DatePickerProps): react.JSX.Element;
+
+/** Up to two initials from a name: "Aurel Agbado" → "AA", "trc" → "T". */
+declare function initials(name: string): string;
+type AvatarProps = {
+    /** Person or organization shown: the accessible name, and the source of the initials. */
+    name: string;
+    src?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+};
+/** Round picture of a person, falling back to their initials on graphite when there is no image or it fails. */
+declare function Avatar({ name, src, size, className }: AvatarProps): react.JSX.Element;
+type AvatarGroupProps = {
+    children: ReactNode;
+    /** Avatars shown before the "+n" counter. */
+    max?: number;
+    /** Accessible name of the counter: a template such as "{count} more", or a function. */
+    moreLabel?: string | ((count: number) => string);
+    size?: AvatarProps["size"];
+    className?: string;
+};
+/** Overlapping avatars, the rest summed up in a "+n" counter. */
+declare function AvatarGroup({ children, max, moreLabel, size, className, }: AvatarGroupProps): react.JSX.Element;
+
+type TagProps = ComponentPropsWithoutRef<"span"> & {
+    /** `accent` for the one tag that matters on a card. */
+    tone?: "default" | "accent";
+    /** Shows a remove button. */
+    onRemove?: () => void;
+    removeLabel?: string;
+    children: ReactNode;
+};
+/** Small label for metadata (status, category, filter). Never placed over photos. */
+declare function Tag({ tone, onRemove, removeLabel, className, children, ...props }: TagProps): react.JSX.Element;
+
+type StatProps = {
+    label: ReactNode;
+    value: ReactNode;
+    /** Change since the previous period: "+12 %". */
+    change?: ReactNode;
+    /** Color of the change: accent when positive, error color when negative. */
+    changeTone?: "positive" | "negative" | "neutral";
+    /** Short context under the value: "vs last month". */
+    description?: ReactNode;
+    className?: string;
+};
+/** A key figure with its label, in a large thin number. */
+declare function Stat({ label, value, change, changeTone, description, className }: StatProps): react.JSX.Element;
+
+type TableColumn<Row> = {
+    key: string;
+    header: ReactNode;
+    /** `right` for numbers, so that digits line up. */
+    align?: "left" | "center" | "right";
+    sortable?: boolean;
+    /** Cell content; the row's `key` field by default. */
+    render?: (row: Row) => ReactNode;
+    /** Value used to sort; the row's `key` field by default. */
+    sortValue?: (row: Row) => string | number | Date;
+};
+type SortState = {
+    key: string;
+    direction: "ascending" | "descending";
+};
+type TableProps<Row> = {
+    columns: TableColumn<Row>[];
+    rows: Row[];
+    /** Unique key of each row. */
+    rowKey: (row: Row) => string;
+    /** Title of the table, read first by screen readers. */
+    caption: ReactNode;
+    /** Hides the caption visually; it stays for screen readers. */
+    hideCaption?: boolean;
+    defaultSort?: SortState;
+    dense?: boolean;
+    emptyText?: ReactNode;
+    className?: string;
+};
+/**
+ * Data table with a caption and sortable columns: each sortable header is a button, and the
+ * current order is announced with `aria-sort`. Scrolls sideways on small screens, in a focusable
+ * region so that keyboard users can scroll it too.
+ */
+declare function Table<Row>({ columns, rows, rowKey, caption, hideCaption, defaultSort, dense, emptyText, className, }: TableProps<Row>): react.JSX.Element;
+
+type SkeletonProps = {
+    width?: number | string;
+    height?: number | string;
+    /** Round, for an avatar. */
+    circle?: boolean;
+    /** Several lines of text, the last one shorter. */
+    lines?: number;
+    className?: string;
+};
+/** Placeholder shapes while content loads. Hidden from screen readers: announce the loading state elsewhere. */
+declare function Skeleton({ width, height, circle, lines, className }: SkeletonProps): react.JSX.Element;
+type SpinnerProps = {
+    size?: "sm" | "md" | "lg";
+    /** Announced to screen readers. */
+    label?: string;
+    className?: string;
+};
+/** Accent arc turning while something loads, announced through `role="status"`. */
+declare function Spinner({ size: s, label, className }: SpinnerProps): react.JSX.Element;
+type ProgressProps = {
+    /** Progress from 0 to `max`; leave out while the total is unknown. */
+    value?: number | null;
+    max?: number;
+    /** Visible label above the bar, also its accessible name. */
+    label?: ReactNode;
+    /** Accessible name when there is no visible label. */
+    "aria-label"?: string;
+    showValue?: boolean;
+    formatValue?: (value: number, max: number) => string;
+    className?: string;
+};
+/** Progress bar filled with the accent; indeterminate without a value. */
+declare function Progress({ value, max, label, "aria-label": ariaLabel, showValue, formatValue, className, }: ProgressProps): react.JSX.Element;
+
+/** A key of the keyboard, for shortcuts: <Kbd>⌘</Kbd> <Kbd>K</Kbd>. */
+declare function Kbd({ className, ...props }: ComponentPropsWithoutRef<"kbd">): react.JSX.Element;
+type DividerProps = {
+    /** Text in the middle of the line: "or". */
+    label?: ReactNode;
+    orientation?: "horizontal" | "vertical";
+    className?: string;
+};
+/** Hairline between groups of content, optionally with a word in the middle. */
+declare function Divider({ label, orientation, className }: DividerProps): react.JSX.Element;
+
+type CodeBlockProps = {
+    /** Source code, also what the copy button copies. */
+    code: string;
+    /** File name shown in a tab: "app/layout.tsx". */
+    title?: ReactNode;
+    /** Language, shown as a small badge next to the title. */
+    language?: string;
+    /** Highlighted rendering of the code, from your own highlighter; plain text by default. */
+    children?: ReactNode;
+    copyLabel?: string;
+    copiedLabel?: string;
+    className?: string;
+};
+/**
+ * Code block with an optional file tab and a copy button that turns into an accent check for a
+ * moment. Bring your own highlighting through `children`; the copied text is always `code`.
+ */
+declare function CodeBlock({ code, title, language, children, copyLabel, copiedLabel, className, }: CodeBlockProps): react.JSX.Element;
+
+export { AccentText, Accordion, Alert, ArrowLeft, ArrowRight, ArrowUp, Avatar, AvatarGroup, BackToTop, Breadcrumbs, Calendar, Card, Check, Checkbox, ChevronDown, ChevronLeft, ChevronRight, Close, CodeBlock, Combobox, Container, DatePicker, Dialog, Divider, Drawer, DropdownMenu, Dropzone, Field, FileInput, Heading, HeroVideo, Input, Kbd, LanguageSwitcher, Menu, PageHero, Pagination, PasswordInput, PillButton, PillLink, PinInput, Popover, Progress, RadioGroup, Section, SegmentedControl, Select, SiteFooter, SiteHeader, Skeleton, Slider, Spinner, Stat, StepNumber, Steps, Switch, Table, Tabs, Tag, Text, Textarea, Toaster, Tooltip, acceptsFile, cx, formatBytes, initials, paginationRange, plainText, toast, validateFiles };
+export type { AccordionItem, AccordionProps, AlertProps, AvatarGroupProps, AvatarProps, BackToTopProps, BreadcrumbItem, BreadcrumbsProps, CardProps, CheckboxProps, CodeBlockProps, ComboboxOption, ComboboxProps, ContainerProps, DatePickerProps, DialogProps, DividerProps, DrawerProps, DropdownMenuProps, DropzoneProps, FieldProps, FileInputProps, FileRejection, FooterLink, HeadingProps, HeadingSize, HeroClip, HeroVideoProps, InputProps, Language, LanguageSwitcherProps, MenuAction, MenuItem, NavItem, NavLink, NavMenu, PageHeroProps, PaginationProps, PasswordInputProps, PillButtonProps, PillLinkProps, PinInputProps, PopoverProps, ProgressProps, RadioGroupProps, RadioOption, SectionProps, SegmentedControlProps, SegmentedOption, SelectProps, SiteFooterProps, SiteHeaderProps, SkeletonProps, SliderProps, SortState, SpinnerProps, StatProps, StepItem, StepsProps, SwitchProps, TabItem, TableColumn, TableProps, TabsProps, TagProps, TextProps, TextareaProps, ToastOptions, ToastTone, ToasterProps, TooltipProps };