tempest-react-sdk 0.73.0 → 0.75.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';
@@ -975,7 +976,22 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
      * development the bar says so in the console when it detects it.
      */
     sticky?: boolean;
-    /** Visual tone. Default `"surface"`. */
+    /**
+     * Visual tone. Default `"surface"`.
+     *
+     * `"inverse"` writes `data-tempest-tone="inverse"` and paints the bar with the
+     * inverse surface's `--tempest-bg`, so the back button, the title and the
+     * components in `actions` invert with it. The tokens are opt-in:
+     * `tempest-react-sdk/styles/inverse.css` for the SDK's own blue, or
+     * `createTheme({ primary, inverse: createInverseSurface })` for yours. With
+     * neither loaded the bar falls back to the page's `--tempest-bg` and
+     * `--tempest-text` — legible, not inverted.
+     *
+     * A separate tone rather than a change to `"primary"`, because the inverse
+     * fill is not always the brand's `500`: for `#0066ff` it is the `800`
+     * (`#042e75`), and turning `"primary"` into it would repaint every bar that
+     * uses it today.
+     */
     tone?: AppBarTone;
     /** Thin bottom border. Default `true`. */
     bordered?: boolean;
@@ -983,7 +999,21 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
     safeArea?: boolean;
 }
 
-export declare type AppBarTone = "surface" | "primary" | "transparent";
+/**
+ * Visual tone of an {@link AppBar}.
+ *
+ * - `"surface"` — the page's surface and text.
+ * - `"primary"` — the brand fill (`--tempest-primary`) with
+ *   `--tempest-primary-foreground` ink. Only the bar's own text and back button
+ *   follow the fill: components in `actions` keep the page's tokens. Measured in
+ *   Chromium over the SDK's `#0066ff`, a primary `Button` inside it has the same
+ *   color as the bar (1:1) and its focus ring reads 1.41:1.
+ * - `"inverse"` — the inverse surface: every color token inverted inside the bar,
+ *   so the components in it are measured against the fill. See
+ *   {@link AppBarProps.tone}.
+ * - `"transparent"` — no background; the text inherits.
+ */
+export declare type AppBarTone = "surface" | "primary" | "inverse" | "transparent";
 
 /**
  * The `code` and `message` a thrown value becomes on the wire.
@@ -2263,13 +2293,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;
 
-export declare interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+/** `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;
+}
+
+/** 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 +2360,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";
 
 /**
@@ -3122,7 +3253,9 @@ declare interface ColorScaleOptions {
  * Combobox — text input with a filterable dropdown of options.
  *
  * Selecting an option fires `onChange(value)`. Typing filters the list.
- * Keyboard: ArrowUp/ArrowDown to navigate, Enter to select, Esc to close.
+ * Keyboard: ArrowUp/ArrowDown to navigate — the active option is announced
+ * through `aria-activedescendant`, focus stays on the input — Enter to select,
+ * Esc to close, and Tab/Shift+Tab leave the field closing the list.
  */
 export declare function Combobox({ options, value, onChange, label, placeholder, helperText, error, disabled, filter, emptyMessage, portal, className, }: ComboboxProps): JSX.Element;
 
@@ -3937,6 +4070,30 @@ 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.
+ *
+ * The result also carries the rules that let a region inside the surface go
+ * back to the page's tokens (`data-tempest-tone="default"`), written for the
+ * selectors in `options`.
+ *
+ * @param options - The brand, plus the status and chart colors the theme names
+ *   and the selectors the surface and the page are written under.
+ * @returns The token map, the scheme it reads as, the fill step used and the
+ *   default-tone rules.
+ */
+export declare function createInverseSurface(options: InverseSurfaceOptions): InverseSurface;
+
 /**
  * Build a typed `localStorage` wrapper around a codec.
  *
@@ -4834,6 +4991,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 +7610,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 +7646,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 +8351,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 +8363,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 +8509,66 @@ 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;
+    /**
+     * CSS written after the surface: the rules that let a region inside it go
+     * back to the page's tokens with `data-tempest-tone="default"`. Rendered by
+     * the generator, so `createTheme` alone does not ship the code that writes it.
+     */
+    rules?: string;
+}
+
+/**
+ * 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[];
+    /**
+     * Selector the surface is written under, which the default-tone rules keep
+     * out of the elements that save the page's values. Default
+     * `'[data-tempest-tone="inverse"]'`.
+     */
+    selector?: string;
+    /**
+     * Selectors the page's schemes are written under, so a region restores a
+     * theme scoped to them too. Default `createTheme`'s: `:root` and
+     * `'[data-tempest-theme="dark"]'`.
+     */
+    page?: PageSelectors;
+}
+
 /**
  * Detects any Android browser.
  *
@@ -10019,8 +10270,10 @@ export declare function moveItem<T>(items: T[], from: number, to: number): T[];
  * removable chips inside the field. Selecting toggles a value; Backspace on an
  * empty query removes the last chip.
  *
- * Keyboard: ArrowUp/ArrowDown navigate, Enter toggles the active option, Esc
- * closes, Backspace (empty input) pops the last chip.
+ * Keyboard: ArrowUp/ArrowDown navigate — the active option is announced through
+ * `aria-activedescendant`, focus stays on the input — Enter toggles the active
+ * option, Esc closes, Backspace (empty input) pops the last chip, and
+ * Tab/Shift+Tab leave the field closing the list.
  */
 export declare function MultiSelect({ options, value, onChange, label, placeholder, helperText, error, disabled, maxItems, filter, emptyMessage, portal, className, }: MultiSelectProps): JSX.Element;
 
@@ -10085,13 +10338,41 @@ export declare interface NavbarProps extends HTMLAttributes<HTMLElement> {
     actions?: ReactNode;
     /** Make the bar sticky at the top of the scroll container. Default `true`. */
     sticky?: boolean;
-    /** Visual tone. Default `"surface"`. */
+    /**
+     * Visual tone. Default `"surface"`.
+     *
+     * `"inverse"` writes `data-tempest-tone="inverse"` and paints the bar with the
+     * inverse surface's `--tempest-bg`, so the components in the slots invert with
+     * it. The tokens are opt-in: `tempest-react-sdk/styles/inverse.css` for the
+     * SDK's own blue, or `createTheme({ primary, inverse: createInverseSurface })`
+     * for yours. With neither loaded the bar falls back to the page's
+     * `--tempest-bg` and `--tempest-text` — legible, not inverted.
+     *
+     * A separate tone rather than a change to `"primary"`, because the inverse
+     * fill is not always the brand's `500`: for `#0066ff` it is the `800`
+     * (`#042e75`), and turning `"primary"` into it would repaint every bar that
+     * uses it today.
+     */
     tone?: NavbarTone;
     /** When set, renders a thin bottom border. Default `true`. */
     bordered?: boolean;
 }
 
-export declare type NavbarTone = "surface" | "primary" | "transparent";
+/**
+ * Visual tone of a {@link Navbar}.
+ *
+ * - `"surface"` — the page's surface and text.
+ * - `"primary"` — the brand fill (`--tempest-primary`) with
+ *   `--tempest-primary-foreground` ink. Only the bar's own text follows the fill:
+ *   components inside it keep the page's tokens. Measured in Chromium over the
+ *   SDK's `#0066ff`, a link button inside it reads 1:1, muted text 1.59:1 and the
+ *   focus ring 1.41:1. Fine for a bar that holds a logo and plain text.
+ * - `"inverse"` — the inverse surface: every color token inverted inside the bar,
+ *   so a primary `Button`, a link, the focus ring and muted text are measured
+ *   against the fill. See {@link NavbarProps.tone}.
+ * - `"transparent"` — no background; the text inherits.
+ */
+export declare type NavbarTone = "surface" | "primary" | "inverse" | "transparent";
 
 export { Navigate }
 
@@ -10987,6 +11268,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 {...} />
@@ -11012,6 +11297,14 @@ export declare interface PageProps extends Omit<HTMLAttributes<HTMLElement>, "ti
     children?: ReactNode;
 }
 
+/** Where the page's schemes are written: the selectors `createTheme` uses. */
+export declare interface PageSelectors {
+    /** Selector of the light scheme. Default `:root`. */
+    selector: string;
+    /** Selector of the dark scheme. Default `'[data-tempest-theme="dark"]'`. */
+    darkSelector: string;
+}
+
 /**
  * Numeric pagination controls. Pair with {@link usePagination} for state.
  *
@@ -12897,6 +13190,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 +13615,111 @@ 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 reaches the section through context
+ * (so wrappers in between do not break the link) and the first one names it;
+ * when it unmounts, the next one takes over. An explicit `aria-labelledby` or
+ * `aria-label` wins over the automatic one, and once mounted with no titled
+ * heading the attribute is left off rather than pointing at nothing.
+ *
+ * The section owns the id (`useId`), so the link is already in the first
+ * render — `renderToString` and the HTML a server sends — where no effect runs.
+ * The parent's attributes are written before any child renders, so the section
+ * cannot know what is below it: it always writes its own id, and the first
+ * titled `SectionHeader` in render order puts that id on its heading. Two
+ * cases cannot be known on the server, and both are settled on hydration
+ * without a mismatch warning: with no titled heading the server attribute is
+ * dropped (until then it resolves to nothing, which Chromium 153 exposes as
+ * the same anonymous group as no attribute at all), and when that first header
+ * has an explicit `id` the attribute moves to it. A consumer that needs the
+ * explicit id in the server HTML passes `aria-labelledby` itself.
+ *
+ * @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 first
+ * titled header takes the section's own id for its heading (unless `id` is
+ * given) and registers it, which is what gives the `region` landmark its
+ * accessible name — in the server HTML too.
+ *
+ * @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.
+     *
+     * `"default"` hands a region inside an inverse section back to the page's
+     * tokens — light or dark, whichever the page is on — by writing
+     * `data-tempest-tone="default"`: a white form or price card in a navy hero.
+     * The rules ship with the inverse tokens, so it costs nothing until those are
+     * loaded, and outside an inverse section the tokens it restores are the ones
+     * already there.
+     */
+    tone?: SectionTone;
+}
+
+/** Surface tone a {@link Section} can take. */
+export declare type SectionTone = "inverse" | "default";
+
 /**
  * iOS-style segmented control. Two-to-five mutually-exclusive options
  * rendered as a single connected pill bar.