@photon-ai/pho-ui 1.4.0 → 2.0.0

package/dist/src/components/phone-input/country-alpha3.d.ts

@@ -0,0 +1,250 @@
+import { CountryCode } from 'libphonenumber-js/min';
+/** ISO 3166-1 alpha-3 for every country code `libphonenumber-js` exposes. */
+export declare const COUNTRY_ALPHA3: {
+    readonly AC: "ASC";
+    readonly AD: "AND";
+    readonly AE: "ARE";
+    readonly AF: "AFG";
+    readonly AG: "ATG";
+    readonly AI: "AIA";
+    readonly AL: "ALB";
+    readonly AM: "ARM";
+    readonly AO: "AGO";
+    readonly AR: "ARG";
+    readonly AS: "ASM";
+    readonly AT: "AUT";
+    readonly AU: "AUS";
+    readonly AW: "ABW";
+    readonly AX: "ALA";
+    readonly AZ: "AZE";
+    readonly BA: "BIH";
+    readonly BB: "BRB";
+    readonly BD: "BGD";
+    readonly BE: "BEL";
+    readonly BF: "BFA";
+    readonly BG: "BGR";
+    readonly BH: "BHR";
+    readonly BI: "BDI";
+    readonly BJ: "BEN";
+    readonly BL: "BLM";
+    readonly BM: "BMU";
+    readonly BN: "BRN";
+    readonly BO: "BOL";
+    readonly BQ: "BES";
+    readonly BR: "BRA";
+    readonly BS: "BHS";
+    readonly BT: "BTN";
+    readonly BW: "BWA";
+    readonly BY: "BLR";
+    readonly BZ: "BLZ";
+    readonly CA: "CAN";
+    readonly CC: "CCK";
+    readonly CD: "COD";
+    readonly CF: "CAF";
+    readonly CG: "COG";
+    readonly CH: "CHE";
+    readonly CI: "CIV";
+    readonly CK: "COK";
+    readonly CL: "CHL";
+    readonly CM: "CMR";
+    readonly CN: "CHN";
+    readonly CO: "COL";
+    readonly CR: "CRI";
+    readonly CU: "CUB";
+    readonly CV: "CPV";
+    readonly CW: "CUW";
+    readonly CX: "CXR";
+    readonly CY: "CYP";
+    readonly CZ: "CZE";
+    readonly DE: "DEU";
+    readonly DJ: "DJI";
+    readonly DK: "DNK";
+    readonly DM: "DMA";
+    readonly DO: "DOM";
+    readonly DZ: "DZA";
+    readonly EC: "ECU";
+    readonly EE: "EST";
+    readonly EG: "EGY";
+    readonly EH: "ESH";
+    readonly ER: "ERI";
+    readonly ES: "ESP";
+    readonly ET: "ETH";
+    readonly FI: "FIN";
+    readonly FJ: "FJI";
+    readonly FK: "FLK";
+    readonly FM: "FSM";
+    readonly FO: "FRO";
+    readonly FR: "FRA";
+    readonly GA: "GAB";
+    readonly GB: "GBR";
+    readonly GD: "GRD";
+    readonly GE: "GEO";
+    readonly GF: "GUF";
+    readonly GG: "GGY";
+    readonly GH: "GHA";
+    readonly GI: "GIB";
+    readonly GL: "GRL";
+    readonly GM: "GMB";
+    readonly GN: "GIN";
+    readonly GP: "GLP";
+    readonly GQ: "GNQ";
+    readonly GR: "GRC";
+    readonly GT: "GTM";
+    readonly GU: "GUM";
+    readonly GW: "GNB";
+    readonly GY: "GUY";
+    readonly HK: "HKG";
+    readonly HN: "HND";
+    readonly HR: "HRV";
+    readonly HT: "HTI";
+    readonly HU: "HUN";
+    readonly ID: "IDN";
+    readonly IE: "IRL";
+    readonly IL: "ISR";
+    readonly IM: "IMN";
+    readonly IN: "IND";
+    readonly IO: "IOT";
+    readonly IQ: "IRQ";
+    readonly IR: "IRN";
+    readonly IS: "ISL";
+    readonly IT: "ITA";
+    readonly JE: "JEY";
+    readonly JM: "JAM";
+    readonly JO: "JOR";
+    readonly JP: "JPN";
+    readonly KE: "KEN";
+    readonly KG: "KGZ";
+    readonly KH: "KHM";
+    readonly KI: "KIR";
+    readonly KM: "COM";
+    readonly KN: "KNA";
+    readonly KP: "PRK";
+    readonly KR: "KOR";
+    readonly KW: "KWT";
+    readonly KY: "CYM";
+    readonly KZ: "KAZ";
+    readonly LA: "LAO";
+    readonly LB: "LBN";
+    readonly LC: "LCA";
+    readonly LI: "LIE";
+    readonly LK: "LKA";
+    readonly LR: "LBR";
+    readonly LS: "LSO";
+    readonly LT: "LTU";
+    readonly LU: "LUX";
+    readonly LV: "LVA";
+    readonly LY: "LBY";
+    readonly MA: "MAR";
+    readonly MC: "MCO";
+    readonly MD: "MDA";
+    readonly ME: "MNE";
+    readonly MF: "MAF";
+    readonly MG: "MDG";
+    readonly MH: "MHL";
+    readonly MK: "MKD";
+    readonly ML: "MLI";
+    readonly MM: "MMR";
+    readonly MN: "MNG";
+    readonly MO: "MAC";
+    readonly MP: "MNP";
+    readonly MQ: "MTQ";
+    readonly MR: "MRT";
+    readonly MS: "MSR";
+    readonly MT: "MLT";
+    readonly MU: "MUS";
+    readonly MV: "MDV";
+    readonly MW: "MWI";
+    readonly MX: "MEX";
+    readonly MY: "MYS";
+    readonly MZ: "MOZ";
+    readonly NA: "NAM";
+    readonly NC: "NCL";
+    readonly NE: "NER";
+    readonly NF: "NFK";
+    readonly NG: "NGA";
+    readonly NI: "NIC";
+    readonly NL: "NLD";
+    readonly NO: "NOR";
+    readonly NP: "NPL";
+    readonly NR: "NRU";
+    readonly NU: "NIU";
+    readonly NZ: "NZL";
+    readonly OM: "OMN";
+    readonly PA: "PAN";
+    readonly PE: "PER";
+    readonly PF: "PYF";
+    readonly PG: "PNG";
+    readonly PH: "PHL";
+    readonly PK: "PAK";
+    readonly PL: "POL";
+    readonly PM: "SPM";
+    readonly PR: "PRI";
+    readonly PS: "PSE";
+    readonly PT: "PRT";
+    readonly PW: "PLW";
+    readonly PY: "PRY";
+    readonly QA: "QAT";
+    readonly RE: "REU";
+    readonly RO: "ROU";
+    readonly RS: "SRB";
+    readonly RU: "RUS";
+    readonly RW: "RWA";
+    readonly SA: "SAU";
+    readonly SB: "SLB";
+    readonly SC: "SYC";
+    readonly SD: "SDN";
+    readonly SE: "SWE";
+    readonly SG: "SGP";
+    readonly SH: "SHN";
+    readonly SI: "SVN";
+    readonly SJ: "SJM";
+    readonly SK: "SVK";
+    readonly SL: "SLE";
+    readonly SM: "SMR";
+    readonly SN: "SEN";
+    readonly SO: "SOM";
+    readonly SR: "SUR";
+    readonly SS: "SSD";
+    readonly ST: "STP";
+    readonly SV: "SLV";
+    readonly SX: "SXM";
+    readonly SY: "SYR";
+    readonly SZ: "SWZ";
+    readonly TA: "TAA";
+    readonly TC: "TCA";
+    readonly TD: "TCD";
+    readonly TG: "TGO";
+    readonly TH: "THA";
+    readonly TJ: "TJK";
+    readonly TK: "TKL";
+    readonly TL: "TLS";
+    readonly TM: "TKM";
+    readonly TN: "TUN";
+    readonly TO: "TON";
+    readonly TR: "TUR";
+    readonly TT: "TTO";
+    readonly TV: "TUV";
+    readonly TW: "TWN";
+    readonly TZ: "TZA";
+    readonly UA: "UKR";
+    readonly UG: "UGA";
+    readonly US: "USA";
+    readonly UY: "URY";
+    readonly UZ: "UZB";
+    readonly VA: "VAT";
+    readonly VC: "VCT";
+    readonly VE: "VEN";
+    readonly VG: "VGB";
+    readonly VI: "VIR";
+    readonly VN: "VNM";
+    readonly VU: "VUT";
+    readonly WF: "WLF";
+    readonly WS: "WSM";
+    readonly XK: "XKX";
+    readonly YE: "YEM";
+    readonly YT: "MYT";
+    readonly ZA: "ZAF";
+    readonly ZM: "ZMB";
+    readonly ZW: "ZWE";
+};
+export declare function getCountryAlpha3(country: CountryCode): string;

package/dist/src/components/phone-input/country-search.d.ts

@@ -0,0 +1,8 @@
+import { CountryCode } from 'libphonenumber-js/min';
+/**
+ * Fold a search string for accent-insensitive matching — `Åland` ↔ `aland`,
+ * `Côte` ↔ `cote`. NFD splits base letters from combining marks; we drop the
+ * marks and lowercase.
+ */
+export declare function foldSearch(value: string): string;
+export declare function countrySearchAliases(country: CountryCode): readonly string[];

package/dist/src/components/phone-input/index.d.ts

@@ -0,0 +1 @@
+export { PhoneInput, type CountryCode, type PhoneInputChangeMeta, type PhoneInputProps, } from './phone-input';

package/dist/src/components/phone-input/phone-input.d.ts

@@ -0,0 +1,47 @@
+import { InputHTMLAttributes, ReactNode, Ref } from 'react';
+import { CountryCode } from 'libphonenumber-js/min';
+import { InputGroupSize } from '../input-group';
+export type { CountryCode };
+export interface PhoneInputChangeMeta {
+    country: CountryCode;
+    isValid: boolean;
+}
+export interface PhoneInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type" | "value" | "defaultValue" | "onChange"> {
+    /** Controlled E.164 value (`+14155550123`), or `""` when empty. */
+    value?: string;
+    /** Uncontrolled initial E.164 value. */
+    defaultValue?: string;
+    /** Fires with the E.164 value (or `""`) and validity metadata. */
+    onValueChange?: (value: string, meta: PhoneInputChangeMeta) => void;
+    /** Country used when the value has no country. @default `"US"` */
+    defaultCountry?: CountryCode;
+    /** Countries offered in the picker. Defaults to every libphonenumber country. */
+    countries?: CountryCode[];
+    /**
+     * Pin the calling-code addon — flag + `+N` stay visible, but the country
+     * picker is replaced by a static label. Use when the number's region is
+     * already known (e.g. confirm-to-destroy flows).
+     */
+    lockCountry?: boolean;
+    /** Size variant, matching Input / Input Group. @default `"md"` */
+    size?: InputGroupSize;
+    /** Render the invalid state (error ring + error-colored hint). */
+    invalid?: boolean;
+    /** Field label (associated for accessibility). */
+    label?: ReactNode;
+    /** Helper text below the field; rendered in the error color when `invalid`. */
+    hint?: ReactNode;
+    /** Node rendered at the right edge of the label row. */
+    labelTrailing?: ReactNode;
+    /** Class applied to the Input Group surface. */
+    wrapperClassName?: string;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * Phone number field — country picker (searchable Combobox) + national number
+ * input on a shared Input Group surface. The committed value is always E.164.
+ */
+export declare function PhoneInput({ value, defaultValue, onValueChange, defaultCountry, countries: countriesProp, lockCountry, size, invalid, label, hint, labelTrailing, disabled, required, placeholder, className, wrapperClassName, id, ref, "aria-label": ariaLabel, onKeyDown, ...props }: PhoneInputProps): import("react").JSX.Element;
+export declare namespace PhoneInput {
+    var displayName: string;
+}

package/dist/src/components/toast/toast.d.ts

@@ -16,7 +16,7 @@ declare function Close({ className, ...props }: StyledProps<typeof BaseToast.Clo
  * maps `useToastManager().toasts` to `Toast.Root`s, then call
  * `useToastManager().add({ title, description })` to show one. Use a toast for
  * confirmation of a background action; for a choice the user must make, use
- * `AlertDialog`.
+ * `Dialog`.
  */
 export declare const Toast: {
     Provider: import('react').FC<import('@base-ui/react').ToastProviderProps>;

package/dist/src/index.d.ts

@@ -12,5 +12,6 @@ export * from './components/input-group';
 export * from './components/card';
 export * from './components/dialog';
 export * from './components/status-view';
+export * from './components/error';
 export * from './sections/sidebar';
 export * from './sections/basic-page';

package/dist/src/sections/basic-page/basic-page.d.ts

@@ -1,24 +1,7 @@
 import { AnchorHTMLAttributes, ComponentProps, ReactNode, Ref } from 'react';
 import { ButtonLinkProps } from '../../components/button';
-/**
- * BasicPage — Pho's standard content page: a page title, section titles, and
- * bordered cards of label/control rows. Settings, billing, members — any
- * single-column management surface.
- *
- * Spacing: wrap the page in `Root` (a 42rem column with `px-5` gutters,
- * vertical padding). `Stack` separates blocks (`gap-10`). Inside a block,
- * children share `gap-3`. Wrap a section title + description in `Header`
- * (`gap-0.5`) so that pair stays tight — don't put them as loose siblings.
- * Parts already carry `px-5`.
- *
- * Navigation: pages may drill into subpages. `RowLink` is a whole-row link
- * (trailing chevron) and `Back` returns to the parent — both render through
- * the host's `LinkProvider`; the URL itself stays the router's job. `Back`
- * floats in `Root`'s top padding, so `Title` never moves between pages that
- * have a back link and pages that don't.
- */
 /** Bordered card that stacks rows with hairline dividers. */
-export declare const BASIC_PAGE_CARD = "divide-y divide-pho-secondary rounded-base border border-pho-secondary bg-pho-primary";
+export declare const BASIC_PAGE_CARD = "rounded-base border border-pho-secondary bg-pho-primary divide-y divide-pho-secondary [&>:has(+[data-basic-page-alert])]:border-b-0";
 /**
  * Standalone callout surface — featured block (invite form, notice, etc.).
  * Don't wrap in `Card`; this is the outer chrome.
@@ -62,33 +45,84 @@ export declare const BASIC_PAGE_ITEM_PANEL_DIVIDED = "-mx-2 -mt-1.5 flex items-c
  * so wide viewports render exactly as before while narrow ones keep a 20px
  * breathing edge instead of running content into the viewport.
  *
- * `relative` anchors `Back`, which floats in the top padding — the reserved
- * zone that keeps `Title` at the same position on every page.
+ * `relative` anchors `Back`, which floats in the top padding. The top zone
+ * is conditional (`:has()`): pages carrying a `Back` reserve 64px for it;
+ * pages without one keep the tighter 48px so the title doesn't sit low.
+ *
+ * The column is also a `min-h-full` flex stack: when the host gives it a
+ * height context (an app shell's scroll pane), a full-page state can claim
+ * the leftover viewport with `flex-1` — `ErrorView className="flex-1"`
+ * centers itself vertically below the title. Hosts without a height context
+ * see a normal column; regular pages are unaffected.
+ *
+ * Root itself never animates — the page entrance lives on `Stack`, so
+ * `Title` and `Back` (the page chrome) stay put while the body below rises
+ * in.
  */
 declare function Root({ className, ...props }: ComponentProps<"div"> & {
     ref?: Ref<HTMLDivElement>;
 }): import("react").JSX.Element;
+export interface BasicPageTitleProps extends ComponentProps<"h1"> {
+    /**
+     * Shared-element key. Pair with the same `morphId` on the subpage's
+     * `Back` and the word morphs between title and back link across the
+     * navigation. Skipped under reduced motion.
+     */
+    morphId?: string;
+    /**
+     * Rise this title into its line on mount — for a subpage title whose line
+     * an inbound Title ↔ Back morph departs from. The moment the word lifts
+     * off, this title floats up from just below it (the Stack physics), so
+     * the two form one upward stream and never overlap. Skipped under
+     * reduced motion.
+     */
+    enter?: boolean;
+    ref?: Ref<HTMLHeadingElement>;
+}
 /**
  * Page title — largest heading on the surface. Plain-text children get a slug
  * `id` for hash targets (`#profile`); the heading itself is not a link.
  */
-declare function Title({ id, className, children, ...props }: ComponentProps<"h1"> & {
-    ref?: Ref<HTMLHeadingElement>;
-}): import("react").JSX.Element;
+declare function Title({ id, morphId, enter, className, children, ...props }: BasicPageTitleProps): import("react").JSX.Element;
+export interface BasicPageStackProps extends Omit<ComponentProps<"div">, RevealMotionConflicts> {
+    ref?: Ref<HTMLDivElement>;
+}
 /**
  * Vertical stack under the page title. Blocks (forms / sections) use `gap-10`;
  * each block lays out its children with `gap-3`.
+ *
+ * Mounting plays the page entrance: the stack rises 12px and fades in on the
+ * Card-shell / Command spring while `Title` / `Back` above stay put. What
+ * that means per state:
+ *
+ * - **Entering the page** — whatever the page first shows (skeleton
+ *   included) rides in with its stack.
+ * - **Skeleton in a separate component** — swapping it for the loaded
+ *   return mounts a fresh stack, so the entrance replays as the
+ *   data-arrival animation. That's the right feel for shapes the skeleton
+ *   couldn't predict (lists of unknown length).
+ * - **1:1 skeleton** — keep ONE stack mounted and branch its children
+ *   (`{pending ? bones : content}`): values then fill in place with no
+ *   motion.
+ *
+ * Static under reduced motion.
  */
-declare function Stack({ className, ...props }: ComponentProps<"div"> & {
-    ref?: Ref<HTMLDivElement>;
-}): import("react").JSX.Element;
+declare function Stack({ className, ...props }: BasicPageStackProps): import("react").JSX.Element;
 /**
- * Title + optional description pair. Keeps that couple tight (`gap-0.5`) so
- * the block's `gap-3` only applies between this header and the card.
+ * Title + optional description pair. No gap between them — the block's
+ * `gap-3` only applies between this header and the card.
  */
-declare function Header({ className, ...props }: ComponentProps<"div"> & {
+export interface BasicPageHeaderProps extends Omit<ComponentProps<"div">, RevealMotionConflicts> {
+    /**
+     * Rise this header into place on mount — the Header flavor of `Title`'s
+     * `enter`, for a subpage title that carries a description: the pair
+     * floats up from below the departing morph word as one block. Put `enter`
+     * here and NOT on the `Title` inside. Skipped under reduced motion.
+     */
+    enter?: boolean;
     ref?: Ref<HTMLDivElement>;
-}): import("react").JSX.Element;
+}
+declare function Header({ enter, className, ...props }: BasicPageHeaderProps): import("react").JSX.Element;
 /**
  * Section heading — same padding as the page title, smaller type. Hashable via
  * slug `id` (not a link).
@@ -111,10 +145,18 @@ declare function Description({ className, ...props }: ComponentProps<"p"> & {
 declare function SectionFooter({ className, ...props }: ComponentProps<"p"> & {
     ref?: Ref<HTMLParagraphElement>;
 }): import("react").JSX.Element;
-/** Bordered card that stacks rows with hairline dividers. */
-declare function Card({ className, ...props }: ComponentProps<"div"> & {
+export interface BasicPageCardProps extends ComponentProps<"div"> {
+    /**
+     * Glide the card's height when its content swaps — bones becoming a
+     * different number of rows, a row created or revoked, an inline state
+     * change. The height follows the content on the page spring instead of
+     * jumping. Reserve it for cards whose contents change while mounted.
+     */
+    animateHeight?: boolean;
     ref?: Ref<HTMLDivElement>;
-}): import("react").JSX.Element;
+}
+/** Bordered card that stacks rows with hairline dividers. */
+declare function Card({ animateHeight, className, children, ...props }: BasicPageCardProps): import("react").JSX.Element;
 /**
  * One card row that can host subviews. Padding matches a plain row, so use it
  * for any row that may grow an `ItemPanel` — primary content goes straight in
@@ -156,9 +198,15 @@ declare function ItemPanel({ divided, className, ...props }: BasicPageItemPanelP
  * Standalone callout. Pair with `CalloutTitle` / `CalloutDescription` (and
  * optional actions) for a featured block — e.g. an invite form. Do not wrap
  * in `Card`; this is already the outer surface.
+ *
+ * Pass `icon` for a decorative glyph anchored to the header block (first
+ * child) — typically a Tabler outline icon. The icon is aria-hidden; keep
+ * meaning in the title/description.
  */
-declare function Callout({ className, ...props }: ComponentProps<"div"> & {
+declare function Callout({ className, icon, children, ...props }: ComponentProps<"div"> & {
     ref?: Ref<HTMLDivElement>;
+    /** Decorative icon, top-right of the header (first child). */
+    icon?: ReactNode;
 }): import("react").JSX.Element;
 /** Callout heading — same type as `SectionTitle`. Hashable via slug `id`. */
 declare function CalloutTitle({ id, className, children, ...props }: ComponentProps<"h2"> & {
@@ -175,25 +223,50 @@ export interface BasicPageRowProps extends Omit<ComponentProps<"div">, "title">
     description?: ReactNode;
     /** Associates the label with a control id. When omitted, the label is not a `<label>`. */
     htmlFor?: string;
+    /**
+     * Stack the label above a full-width control instead of the default
+     * label-left / control-right layout at `sm+`. Keeps the compact `gap-3`
+     * rhythm — the default row's `justify-between` would otherwise stretch
+     * label and control apart under `min-h-[4.25rem]`.
+     */
+    stacked?: boolean;
     ref?: Ref<HTMLDivElement>;
 }
 /**
  * One row: label (+ optional description) left, control right.
  * Pass `htmlFor` when the row wraps a labelled input; omit it for display/
- * action rows (avatar, danger-zone delete).
+ * action rows (avatar, danger-zone delete). Pass `stacked` for full-width
+ * controls that sit under the label.
  */
-declare function Row({ label, description, htmlFor, className, children, ...props }: BasicPageRowProps): import("react").JSX.Element;
+declare function Row({ label, description, htmlFor, stacked, className, children, ...props }: BasicPageRowProps): import("react").JSX.Element;
 /** Read-only value on the right side of a row (email, etc.). */
 declare function Value({ className, ...props }: ComponentProps<"p"> & {
     ref?: Ref<HTMLParagraphElement>;
 }): import("react").JSX.Element;
+export interface BasicPageAlertProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The caught value — a problem body, an `Error` wrapping one, or unknown. */
+    error?: unknown;
+    /** Override the derived message. */
+    children?: ReactNode;
+    /**
+     * Explicit presence override — defaults to whether there is anything to
+     * show, so the reveal plays as the mutation's error comes and goes.
+     */
+    show?: boolean;
+    ref?: Ref<HTMLDivElement>;
+}
 /**
- * Inline error under a row (still inside the card). Matches card horizontal
- * padding so hosts don't re-apply `px-5`.
+ * Server error under a row, still inside the card — the partial failure
+ * ("Couldn't update your name"), rendered by `Error` from the problem body.
+ * Keep it mounted and pass the mutation's error: the line reveals and
+ * collapses on `Footer`'s height spring + fade. The card drops its divider
+ * above the line so it reads as part of the row it belongs to. Matches card
+ * horizontal padding — don't re-apply `px-5`.
+ *
+ * For a page that failed to load outright, swap the stack for an `ErrorView`
+ * instead.
  */
-declare function Alert({ className, ...props }: ComponentProps<"p"> & {
-    ref?: Ref<HTMLParagraphElement>;
-}): import("react").JSX.Element;
+declare function Alert({ error, show, className, children, ...props }: BasicPageAlertProps): import("react").JSX.Element;
 export interface BasicPageFooterProps extends ComponentProps<"div"> {
     /**
      * Animated presence for dirty-state bars: the card glides open/closed on a
@@ -210,11 +283,56 @@ export interface BasicPageFooterProps extends ComponentProps<"div"> {
  * out following the onboarding card's motion language.
  */
 declare function Footer({ show, className, ...props }: BasicPageFooterProps): import("react").JSX.Element;
+/**
+ * DOM handlers whose React signatures clash with Motion's gesture props of
+ * the same name on `motion.*` elements — excluded from `Reveal`'s public API
+ * (same policy as Button).
+ */
+type RevealMotionConflicts = "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration" | "onDrag" | "onDragStart" | "onDragEnd" | "onDragEnter" | "onDragExit" | "onDragLeave" | "onDragOver" | "onDrop";
+export interface BasicPageRevealProps extends Omit<ComponentProps<"div">, RevealMotionConflicts> {
+    /**
+     * Animated presence for a `Stack` block that comes and goes: keep the
+     * block mounted and drive it with `show` — it glides open and closed
+     * (height + fade) on the page spring, with the Stack's `gap-10`
+     * compensated so nothing jumps when it fully collapses. Omit `show` for
+     * the one-shot data-arrival entrance.
+     */
+    show?: boolean;
+    /**
+     * Which gap the presence variant compensates while collapsing —
+     * `"stack"` for a Stack block (`gap-10`), `"block"` for an element
+     * inside a block (`gap-3`). @default "stack"
+     */
+    gap?: "stack" | "block";
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Data-arrival entrance for regions whose shape the skeleton couldn't
+ * predict — a list of unknown length, a region that depends on the data.
+ * Wrap that region (keeping `Title` and 1:1 chrome outside): once the shape
+ * is known it rises 12px and fades in on the Card-shell / Command spring,
+ * the same physics as the `Footer` / `Alert` reveals. When the skeleton
+ * mirrors the loaded layout element for element, skip the reveal — values
+ * fill into a shape that never moves. The page *entrance* is separate and
+ * already built into `Stack`: whatever the page first shows (including the
+ * skeleton) rides that. Static under reduced motion.
+ *
+ * With `show`, Reveal becomes an animated-presence block instead (the
+ * `Footer` grammar): a whole section of the Stack that appears or leaves at
+ * runtime glides open/closed while its neighbours follow.
+ */
+declare function Reveal({ show, gap, className, ...props }: BasicPageRevealProps): import("react").JSX.Element;
 export interface BasicPageBackProps extends Omit<ButtonLinkProps, "variant" | "size" | "shape" | "prefix" | "suffix" | "svgOnly" | "href"> {
     /** Parent destination — rendered through the host's `LinkProvider`. */
     href: string;
     /** Label — name the parent page. @default "Back" */
     children?: ReactNode;
+    /**
+     * Shared-element key. Pair with the same `morphId` on the parent page's
+     * `Title` and the word morphs between title and back link across the
+     * navigation. Skipped under reduced motion.
+     */
+    morphId?: string;
 }
 /**
  * Back link for a subpage — a small ghost `ButtonLink`; place inside `Root`,
@@ -226,11 +344,11 @@ export interface BasicPageBackProps extends Omit<ButtonLinkProps, "variant" | "s
  * 40px in (`px-5` root gutter + `px-5` title pad); inside a `sm` ghost button
  * the label sits 29.75px in (8px icon-side pad + 15.75px chevron, 1.125em at
  * the 14px `text-base`, + 4px gap + 2px label-span `px-0.5`) — so `left` is
- * the 10.25px difference. `top-2` centers the 32px button in the 48px
+ * the 10.25px difference. `top-4` centers the 32px button in the 64px
  * reserved zone. The chevron and the ghost hover pill hang in the padding —
  * the usual optical alignment for borderless controls.
  */
-declare function Back({ href, className, children, ...props }: BasicPageBackProps): import("react").JSX.Element;
+declare function Back({ href, className, morphId, children, ...props }: BasicPageBackProps): import("react").JSX.Element;
 export interface BasicPageRowLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "title"> {
     /** Left-side field name — plain text, or compose with a trailing badge. */
     label: ReactNode;
@@ -246,7 +364,8 @@ export interface BasicPageRowLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnc
 }
 /**
  * A row that navigates — the whole row is one link into a subpage, with a
- * trailing chevron cue. Same geometry as `Row`; hover lifts the row, and
+ * trailing chevron cue. Always horizontal: a column stack would park the
+ * chevron under the label on narrow viewports. Hover lifts the row, and
  * first/last rows follow the card's corner radius.
  */
 declare function RowLink({ label, description, leading, href, className, children, ...props }: BasicPageRowLinkProps): import("react").JSX.Element;
@@ -279,7 +398,7 @@ declare function RowLink({ label, description, leading, href, className, childre
  *         </BasicPage.Row>
  *       </BasicPage.Card>
  *     </div>
- *     <BasicPage.Callout>
+ *     <BasicPage.Callout icon={<IconMail stroke={1.25} />}>
  *       <BasicPage.Header>
  *         <BasicPage.CalloutTitle>Invitations</BasicPage.CalloutTitle>
  *         <BasicPage.CalloutDescription>…</BasicPage.CalloutDescription>
@@ -328,5 +447,6 @@ export declare const BasicPage: {
     Value: typeof Value;
     Alert: typeof Alert;
     Footer: typeof Footer;
+    Reveal: typeof Reveal;
 };
 export {};