tempest-react-sdk 0.72.0 → 0.74.0

package/dist/tempest-react-sdk.d.ts

@@ -1,3 +1,4 @@
+import { AnchorHTMLAttributes } from 'react';
 import { AnimationEventHandler } from 'react';
 import { AriaRole } from 'react';
 import { BrowserRouter } from 'react-router';
@@ -2263,13 +2264,64 @@ export declare function buildOpenInChromeIntent(): string | null;
  *
  * Sizes are density-aware — they read from `--tempest-control-height-*`
  * tokens which respond to the `data-tempest-density` attribute.
+ *
+ * With `href` it renders an `<a>` with the same look: a call to action that
+ * navigates keeps the middle click, Ctrl+click, "open in new tab" and the URL
+ * preview, which a `<button>` calling `location.assign` loses. `target="_blank"`
+ * gets `noopener noreferrer`. An `<a>` has no `disabled`, so a disabled or loading
+ * link gets `aria-disabled="true"`, `role="link"`, `tabIndex={-1}`, no `href`, and
+ * its click and middle-click cancelled.
+ *
+ * To style another element — a react-router `Link` — use {@link ButtonSlot}. It is
+ * a separate component, not an `asChild` prop, so an app that never uses it does
+ * not ship the prop merge and ref composition it needs.
+ *
+ * The ref is typed per mode: `HTMLButtonElement`, or `HTMLAnchorElement` with
+ * `href`. `forwardRef` takes one ref type for all props, so its result is re-typed
+ * to the per-mode union — the runtime is plain `forwardRef`.
+ *
+ * @example
+ * <Button onClick={save}>Salvar</Button>
+ *
+ * @example
+ * <Button href="https://wa.me/5586999999999" target="_blank" rightIcon={<ExternalLink />}>
+ *     Fale conosco
+ * </Button>
  */
-export declare function Button({ variant, size, loading, fullWidth, iconOnly, pill, leftIcon, rightIcon, disabled, className, children, ...props }: ButtonProps): JSX.Element;
+export declare const Button: ButtonComponent;
+
+/** `Button` rendering a native `<button>` — the default, when `href` is not set. */
+export declare interface ButtonAsButtonProps extends ButtonBaseProps, ButtonHTMLAttributes<HTMLButtonElement> {
+    href?: undefined;
+}
+
+/**
+ * `Button` rendering an `<a href>` — a call to action that navigates.
+ *
+ * `type` is a `<button>` attribute and is rejected here; `target` and `rel` are
+ * forwarded, and `target="_blank"` always gets `noopener noreferrer` added.
+ */
+export declare interface ButtonAsLinkProps extends ButtonBaseProps, Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "type"> {
+    /** Destination. Its presence is what makes the button an `<a>`. */
+    href: string;
+    type?: never;
+}
 
-export declare interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+/** The look of the button — shared by `Button` (`<button>` or `<a>`) and `ButtonSlot`. */
+export declare interface ButtonBaseProps {
     variant?: ButtonVariant;
     size?: ButtonSize;
+    /**
+     * Shows the spinner, keeps the width, sets `aria-busy` and blocks activation —
+     * a `<button>` gets `disabled`, a link gets the disabled-link semantics.
+     */
     loading?: boolean;
+    /**
+     * Blocks activation. On a `<button>` this is the native `disabled`; an `<a>` has
+     * no such attribute, so a link gets `aria-disabled="true"`, `tabIndex={-1}` and
+     * no navigable `href` instead.
+     */
+    disabled?: boolean;
     fullWidth?: boolean;
     /** Removes horizontal padding and forces a square footprint (use with `aria-label`). */
     iconOnly?: boolean;
@@ -2279,8 +2331,58 @@ export declare interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElem
     rightIcon?: ReactNode;
 }
 
+/** `Button`'s call signature: one props union, each member with its own ref type. */
+declare type ButtonComponent = ((props: ButtonPropsWithRef) => ReactElement) & {
+    displayName?: string;
+};
+
+export declare type ButtonProps = ButtonAsButtonProps | ButtonAsLinkProps;
+
+/**
+ * Each mode's props with the ref type of the element it renders, so a `ref` to an
+ * `HTMLButtonElement` on a link is a type error.
+ */
+declare type ButtonPropsWithRef = (ButtonAsButtonProps & RefAttributes<HTMLButtonElement>) | (ButtonAsLinkProps & RefAttributes<HTMLAnchorElement>);
+
 export declare type ButtonSize = "xs" | "sm" | "md" | "lg" | "xl";
 
+/**
+ * Lends the `Button` look to its single child element instead of rendering one —
+ * the `asChild`/Slot pattern. `<ButtonSlot><Link to="/x">Go</Link></ButtonSlot>`
+ * styles a react-router `Link`, so the route changes without a reload, and no
+ * router is imported here.
+ *
+ * It is a component of its own rather than an `asChild` prop on `Button` because
+ * of what it costs: the prop merge and ref composition are ~0.6 kB brotli, and a
+ * prop is a runtime branch no bundler can drop, so every app using `Button` paid
+ * for it. As a separate export it is tree-shaken away where unused.
+ *
+ * Merge rules: classes are joined (a function `className`, as `NavLink` takes,
+ * stays a function); `ButtonSlot`'s props win over the child's, because they carry
+ * the disabled semantics; handlers run `ButtonSlot`'s first and skip the child's
+ * when the event was prevented; both refs receive the node. A child with
+ * `target="_blank"` gets `noopener noreferrer`.
+ *
+ * Disabled or loading: `aria-disabled="true"`, `tabIndex={-1}`, click and
+ * middle-click cancelled — a router `Link` then skips its navigation because the
+ * event arrives prevented. A plain `<a href>` child also loses the `href` and gets
+ * `role="link"`; a `Link` computes its own `href`, which stays in the DOM.
+ *
+ * @example
+ * <ButtonSlot variant="outline">
+ *     <Link to="/planos">Ver planos</Link>
+ * </ButtonSlot>
+ *
+ * @throws {Error} When `children` is not a single React element.
+ */
+export declare const ButtonSlot: ForwardRefExoticComponent<ButtonSlotProps & RefAttributes<HTMLElement>>;
+
+/** Props of {@link ButtonSlot}: the `Button` look, applied to the single child. */
+export declare interface ButtonSlotProps extends ButtonBaseProps, Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The one element that receives the classes, props and ref — e.g. a router `Link`. */
+    children: ReactElement;
+}
+
 export declare type ButtonVariant = "primary" | "secondary" | "danger" | "success" | "ghost" | "soft" | "outline" | "link";
 
 /**
@@ -3937,6 +4039,24 @@ export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): Fea
     set: (key: string, value: FlagValue) => void;
 };
 
+/**
+ * Build the inverse surface for a brand.
+ *
+ * The fill is the brand's own `500` whenever it can carry the scheme, and
+ * otherwise the nearest ramp step that can (see {@link FILL_CANDIDATES}). Whether
+ * the surface reads light-on-dark or dark-on-light follows the fill, so a yellow
+ * brand gets dark ink and a navy one white — the same pick `createTheme` makes
+ * for `--tempest-primary-foreground`.
+ *
+ * The values are literal colors, not references to the page's ramp, so the
+ * section paints the same in the light and the dark page scheme: the brand is
+ * the brand in both.
+ *
+ * @param options - The brand, plus the status and chart colors the theme names.
+ * @returns The token map, the scheme it reads as, and the fill step used.
+ */
+export declare function createInverseSurface(options: InverseSurfaceOptions): InverseSurface;
+
 /**
  * Build a typed `localStorage` wrapper around a codec.
  *
@@ -4834,6 +4954,25 @@ export declare interface CreateThemeOptions {
     selector?: string;
     /** Selector the dark tokens are written under. Default `'[data-tempest-theme="dark"]'`. */
     darkSelector?: string;
+    /**
+     * Also emit the inverse surface — the token set for a section painted in the
+     * brand color — by passing its generator, `createInverseSurface`. Off by
+     * default; ignored without `primary`.
+     *
+     * The generator is passed in rather than switched on with `true` so that
+     * `createTheme` never imports it: an app that does not paint a section in
+     * its brand does not ship the 1.68 kB brotli it costs.
+     *
+     * @example
+     * ```ts
+     * import { createInverseSurface, createTheme } from "tempest-react-sdk";
+     *
+     * createTheme({ primary: "#03184b", inverse: createInverseSurface });
+     * ```
+     */
+    inverse?: InverseSurfaceGenerator;
+    /** Selector the inverse tokens are written under. Default `'[data-tempest-tone="inverse"]'`. */
+    inverseSelector?: string;
 }
 
 /**
@@ -7434,6 +7573,13 @@ export declare interface FormRowProps extends HTMLAttributes<HTMLDivElement> {
  * Has its own `layout`/`columns`/`gap` so subsets can stack while the parent
  * grids (or vice versa).
  *
+ * The header is deliberately not a `SectionHeader`: a field group sits one step
+ * below a page section, and its title is `text-lg` / semibold / `leading-snug`
+ * with `space-3` below, against `text-2xl` / bold / `leading-tight` with
+ * `space-5` for `SectionHeader`. Sharing the component would either grow every
+ * form group to page-section size or add a size switch to `SectionHeader` that
+ * only this caller uses.
+ *
  * @example
  * <FormSection title="Endereço" description="Usado para entrega" layout="grid" columns={3}>
  *     <Input label="CEP" />
@@ -7463,6 +7609,12 @@ export declare interface GeneratedTheme {
     light: Record<string, string>;
     /** Dark-scheme custom properties. */
     dark: Record<string, string>;
+    /**
+     * Inverse-surface custom properties — literal colors, identical under the
+     * light and the dark page scheme. Present only when the theme names a
+     * `primary` and passes `inverse`.
+     */
+    inverse?: Record<string, string>;
     /** Both blocks rendered as CSS, ready for {@link applyTheme} or a stylesheet. */
     css: string;
 }
@@ -8162,7 +8314,9 @@ export declare interface InstallBannerProps {
  * Nothing renders only when there is genuinely nothing to offer — already
  * installed, running standalone, or inside the decline cooldown.
  *
- * Inherits every {@link Button} prop (`variant`, `size`, `leftIcon`, …).
+ * Inherits every {@link Button} prop of the `<button>` mode (`variant`, `size`,
+ * `leftIcon`, …) but not `href`: its click opens the install prompt
+ * or toggles the instruction, which is an action, not a navigation.
  *
  * @example
  * <InstallButton variant="primary" leftIcon={<Download />} />
@@ -8172,7 +8326,7 @@ export declare interface InstallBannerProps {
  */
 export declare function InstallButton({ label, hintLabel, onResult, renderHint, manualFallbackDelayMs, wrapperClassName, ...props }: InstallButtonProps): JSX.Element | null;
 
-export declare interface InstallButtonProps extends Omit<ButtonProps, "onClick" | "children"> {
+export declare interface InstallButtonProps extends Omit<ButtonAsButtonProps, "onClick" | "children"> {
     /** Button label. Default `"Instalar app"`. */
     label?: ReactNode;
     /**
@@ -8318,6 +8472,48 @@ export declare function installSkipWaitingListener(): void;
 
 export declare type InterpolationValues = Record<string, string | number>;
 
+/** Which way the inverse surface reads: light ink on a dark fill, or the reverse. */
+export declare type InverseScheme = "light" | "dark";
+
+/** The inverse surface for one brand. */
+export declare interface InverseSurface {
+    /** Every color custom property the surface redefines, as literal colors. */
+    tokens: Record<string, string>;
+    /**
+     * `"dark"` when the fill carries light ink (a navy brand), `"light"` when it
+     * carries dark ink (a yellow brand). Written as `color-scheme`, so native
+     * controls inside the section follow the fill rather than the page.
+     */
+    scheme: InverseScheme;
+    /** Step of the brand's light ramp used as the fill. */
+    step: ScaleStep;
+}
+
+/**
+ * The inverse-surface generator `createTheme` calls when it is handed one —
+ * in practice `createInverseSurface`.
+ *
+ * A function rather than a flag on purpose: `createTheme` never imports the
+ * generator, so an app that does not paint a section in its brand does not ship
+ * it. Measured with `npx size-limit`, `{ createTheme }` is 3.18 kB brotli on its
+ * own and 4.86 kB with the generator inside it — what a boolean option would
+ * have charged every theme.
+ */
+export declare type InverseSurfaceGenerator = (options: InverseSurfaceOptions) => InverseSurface;
+
+/** Input for an {@link InverseSurfaceGenerator} — `createInverseSurface`. */
+export declare interface InverseSurfaceOptions {
+    /** Brand color — the fill is picked from its ramp. */
+    primary: string;
+    /**
+     * Status colors the theme names; the rest use the SDK's defaults. A named
+     * `danger` is also the warm pole of the diverging chart scale, as on the page.
+     */
+    statuses?: Partial<Record<ThemeStatus, string>>;
+    /** Categorical chart colors the theme names; else the SDK's defaults. */
+    chart?: readonly string[];
+}
+
 /**
  * Detects any Android browser.
  *
@@ -10987,6 +11183,10 @@ declare type OverriddenDomProps_9 = "onSubmit" | "value" | "defaultValue" | "row
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
  * with `Container` when you want a max-width content well.
  *
+ * The header is a `SectionHeader` at `level={1}`, so the page title and the
+ * `<h2>` of each section below it share one look; when every header slot is
+ * empty no `<header>` is rendered.
+ *
  * @example
  * <Page title="Pedidos" description="Acompanhe seus pedidos" actions={<Button>Novo</Button>}>
  *     <Table {...} />
@@ -12897,6 +13097,70 @@ export declare interface RetryOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Animate content into view the first time it is scrolled to.
+ *
+ * The three failure modes of a hand-rolled version are handled here, not left to
+ * the docs:
+ *
+ * - **Reduced motion.** Under `prefers-reduced-motion: reduce` the stylesheet
+ *   pins the element visible with no transform and no transition, whatever
+ *   state it is in — so the setting also wins when it changes mid-session.
+ * - **No `IntersectionObserver`** (old engines, some crawlers, tests): the
+ *   element stays in the `"static"` state, which is plain visible content. It is
+ *   never hidden waiting for an observation that cannot come.
+ * - **Taller than the viewport.** A box three viewports tall never reaches a
+ *   ratio of 0.5, so a raw observer with that threshold never reveals it. The
+ *   threshold is rescaled by the highest ratio the element can reach (see
+ *   `effectiveThreshold`), read from the first observation.
+ *
+ * Content is hidden only when the client can observe: the server snapshot of
+ * `useSyncExternalStore` is `"static"`, so markup rendered without JavaScript —
+ * or before hydration — is visible. The transition is declared on the `"shown"`
+ * state only, so the switch to `"hidden"` on mount is instant instead of a
+ * fade-out, and with `once={false}` leaving the viewport hides without motion.
+ *
+ * With `once={false}` the element hides only once it is fully out of view. Hiding
+ * on the threshold would oscillate: the hidden state translates the box, which
+ * moves it back across the same threshold.
+ *
+ * @example
+ * <ul>
+ *   {steps.map((step, index) => (
+ *     <Reveal key={step.id} as="li" delay={index * 80}>
+ *       {step.title}
+ *     </Reveal>
+ *   ))}
+ * </ul>
+ */
+export declare function Reveal({ as, variant, delay, duration, once, threshold, rootMargin, className, style, children, ...props }: RevealProps): JSX.Element;
+
+export declare interface RevealProps extends HTMLAttributes<HTMLElement> {
+    /** Intrinsic element to render, e.g. `"li"` inside a list. Defaults to `"div"`. */
+    as?: keyof JSX.IntrinsicElements;
+    /** How the content enters. Defaults to `"up"`. */
+    variant?: RevealVariant;
+    /** Wait before the entrance starts, in ms. Stagger siblings with `index * step`. */
+    delay?: number;
+    /** Length of the entrance, in ms. Defaults to `--tempest-duration-slower`. */
+    duration?: number;
+    /** Reveal once and stop observing. With `false`, it hides again once fully out of view. Defaults to `true`. */
+    once?: boolean;
+    /**
+     * Fraction of the element — or of the viewport, when the element is taller
+     * than it — that must be visible to reveal. Defaults to `0.15`.
+     */
+    threshold?: number;
+    /** Margin around the root, as in `IntersectionObserver`. Defaults to `"0px"`. */
+    rootMargin?: string;
+}
+
+/** Visual state written to `data-state`. */
+export declare type RevealState = "static" | "hidden" | "shown";
+
+/** Direction the content travels from, or `"fade"` / `"scale"` for no travel. */
+export declare type RevealVariant = "fade" | "up" | "down" | "left" | "right" | "scale";
+
 /** Serialize sRGB channels (`0`–`1`, clamped) back to a `#rrggbb` string. */
 export declare function rgbToHex(r: number, g: number, b: number): string;
 
@@ -13258,6 +13522,91 @@ export declare interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInp
     wrapperClassName?: string;
 }
 
+/**
+ * `<section>` that takes its accessible name from the `SectionHeader` inside it.
+ *
+ * A `<section>` is exposed as a `region` landmark only when it has an
+ * accessible name; without one it is an anonymous group and screen-reader
+ * landmark navigation skips it. Wiring `aria-labelledby` to the heading id is
+ * the same mechanical step on every page, so the section does it: every
+ * `SectionHeader` with a `title` below it registers its id through context (so
+ * wrappers in between do not break the link) and the first one mounted names
+ * the section; when it unmounts, the next one takes over. An explicit
+ * `aria-labelledby` or `aria-label` wins over the registered one, and with no
+ * heading the attribute is left off rather than pointing at nothing.
+ *
+ * @example
+ * <Section>
+ *     <SectionHeader title="Planos" />
+ *     <PlanGrid />
+ * </Section>
+ *
+ * @example
+ * <Section tone="inverse">
+ *     <SectionHeader title="Comece agora" />
+ *     <Button>Criar conta</Button>
+ * </Section>
+ */
+export declare function Section({ children, tone, ...props }: SectionProps): JSX.Element;
+
+/**
+ * Header of a page or of one section of it: eyebrow, title, description and
+ * actions, with the same look `Page` uses for its own header.
+ *
+ * The heading level is a prop because one page needs one `<h1>` and many
+ * `<h2>` that look alike; the visual stays the same at every level so the
+ * outline is picked by meaning, not by size. Inside a `<Section>` the heading
+ * id is registered with it, which is what gives the `region` landmark its
+ * accessible name.
+ *
+ * @example
+ * <Section>
+ *     <SectionHeader eyebrow="Soluções" title="O que podemos desenvolver" align="center" />
+ *     <p>Conteúdo da seção.</p>
+ * </Section>
+ */
+export declare function SectionHeader({ title, eyebrow, description, actions, level, align, id, className, ...props }: SectionHeaderProps): JSX.Element | null;
+
+export declare type SectionHeaderAlign = "start" | "center";
+
+export declare type SectionHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export declare interface SectionHeaderProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "id"> {
+    /** Heading text, rendered as `<h{level}>`. */
+    title?: ReactNode;
+    /** Short label above the title (category, breadcrumbs). */
+    eyebrow?: ReactNode;
+    /** Supporting text rendered below the title. */
+    description?: ReactNode;
+    /** Trailing slot for buttons or menus. */
+    actions?: ReactNode;
+    /** Heading level — semantics only, the look does not change with it. Default `2`. */
+    level?: SectionHeaderLevel;
+    /** Horizontal alignment of the text block. Default `"start"`. */
+    align?: SectionHeaderAlign;
+    /** Id of the heading element. Generated with `useId` when absent. */
+    id?: string;
+}
+
+export declare interface SectionProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * `"inverse"` paints the section in the brand color and inverts every color
+     * token inside it, by writing `data-tempest-tone="inverse"`. The tokens are
+     * opt-in, because most apps never paint a section in the brand: they come
+     * from `tempest-react-sdk/styles/inverse.css` for the SDK's own blue, or from
+     * `createTheme({ primary, inverse: createInverseSurface })` for yours, each
+     * measured against the fill (text and muted text at 4.5:1 or more, the focus
+     * ring at 3:1 or more). With neither loaded the attribute matches nothing and
+     * the section keeps the page's tokens — legible, not inverted. The prop
+     * exists so the tone is typed: a typo in a hand-written attribute fails
+     * silently, a typo here fails the build.
+     */
+    tone?: SectionTone;
+}
+
+/** Surface tone a {@link Section} can take. */
+export declare type SectionTone = "inverse";
+
 /**
  * iOS-style segmented control. Two-to-five mutually-exclusive options
  * rendered as a single connected pill bar.