import type { ControlSize } from "@charcuterie/tokens";
import type { Placement } from "@floating-ui/react";
import type { ReactElement, ReactNode } from "react";
import type { NavItem } from "./navItems.ts";
/**
 * Where the destinations are drawn. Not *whether* — see
 * `useNavLayout`, which answers that from the width.
 */
export type NavLayout = "bar" | "bottom" | "menu" | "rail" | "railIcons";
type NavCommonProps = {
    /**
     * The destinations, in the order the product reads.
     *
     * Annotate the array as `NavRailItem[]` when the app uses a rail:
     * it is the same shape with `icon` made **required**, because
     * `railIcons` takes the label away and an item with no glyph is a
     * blank square that still navigates. `NavItem` keeps `icon`
     * optional so that a `bar`, where the label never goes anywhere,
     * does not have to invent one.
     */
    items: readonly NavItem[];
    /**
     * The address the app is at — usually `location.pathname`. The
     * item that matches wears `aria-current="page"`.
     *
     * Omitted means nothing is current, which is honest on a screen
     * the nav does not contain (a modal route, an error page) and is
     * better than marking the closest thing.
     */
    activeHref?: string;
    className?: string;
    /**
     * The `<nav>`'s accessible name. Default `"Main"`.
     *
     * Required in spirit and defaulted in practice: two unnamed
     * navigations on one page are two landmarks a screen reader
     * announces identically, which is axe's `landmark-unique`. An app
     * with a second nav — a queue's sub-navigation, a footer — names
     * that one and leaves this one alone.
     */
    label?: string;
};
type NavPlacedProps = NavCommonProps & {
    /**
     * **Initial** only, and the bar owns it from then on — the same
     * uncontrolled contract every other component here has. It exists
     * so a story (and a screenshot) can show the menu open; an app
     * almost never passes it. `bar` only.
     */
    isMenuVisible?: boolean;
    layout?: "bar" | "bottom" | "rail" | "railIcons";
    /**
     * Where the trigger sits in the bar's track once the row has
     * folded. `"end"` when the header puts its own actions at the far
     * edge, so the fold control joins them instead of hugging the
     * wordmark with the whole track empty after it.
     *
     * It reaches **only** the folded row, which holds exactly one
     * item — so it cannot disturb where the links sit when the bar is
     * whole, and there is deliberately no prop that can.
     */
    menuAlign?: "end" | "start";
    /**
     * The folded trigger's glyph. **No default** — the library ships
     * no icons, and a hamburger renders as nothing where the font
     * lacks it. With no icon the trigger is a text button reading
     * `menuLabel`, which works everywhere.
     */
    menuIcon?: ReactNode;
    /**
     * Names the trigger and, through it, the panel it opens. A
     * `role="dialog"` takes no accessible name from its content.
     */
    menuLabel?: string;
    menuPlacement?: Placement;
    size?: ControlSize;
};
type NavMenuProps = NavCommonProps & {
    isVisible: boolean;
    layout: "menu";
    onDismiss: () => void;
    placement?: Placement;
    /** The control the panel hangs off. **Cloned, not wrapped.** */
    trigger: ReactElement;
};
/**
 * The union splits on `menu` and **only** on `menu`, because that is
 * the one layout an app cannot reach with a variable: its trigger
 * goes in the `Header`, so the app is already writing the branch.
 *
 * Everything else takes `layout={navLayout.layout}` straight from
 * `useNavLayout` — which is a *variable*, not a literal, so a union
 * that also split `items` by layout would force a `switch` at the
 * one call site this component exists to make short.
 */
export type NavProps = NavMenuProps | NavPlacedProps;
/**
 * The app's destinations — a header row, a side rail, a collapsed
 * rail, a strip along the foot of the Narrow View, or a panel behind
 * one control. The same list, drawn where it fits.
 *
 * ## What was actually missing
 *
 * `Shell` / `Header` / `Rail` / `Main` shipped the page frame on
 * 2026-08-10 and left the **contents of the nav rail empty**. Twelve
 * UI repos, and exactly two of them had a `<nav>` at all: Docket
 * hand-rolled a row of `NavLink`s with the collapse rule in the
 * app's own stylesheet, Folio hand-rolled another, and the other ten
 * had no destinations anywhere. The two that existed already
 * disagreed — Docket *wraps* below its breakpoint and stands three
 * lines tall on a phone, which is not a decision anybody made, it is
 * what `flex-wrap` does when nobody writes the other rule.
 *
 * ## Every item is a real link
 *
 * `<a href>`, through the injected `RouterLinkProvider` — see
 * `NavLink`, which is where that argument is written down.
 *
 * ## `aria-current="page"`, and exactly one of them
 *
 * `resolveActiveKey` takes the **deepest** matching path, so an app
 * holding both `/settings` and `/settings/labels` marks the page the
 * reader is actually on rather than both.
 *
 * ## `bar` folds WHOLE, and it is measured
 *
 * There is no `collapseAt` and no media query on this axis. The bar
 * reads the width its links actually have and folds when their sum
 * stops fitting, so a longer label, a tenth destination, a
 * `data-density="kiosk"` or a reader at 175% browser zoom each move
 * the fold on their own. mux-magic collapses at a hardcoded `480px`
 * and plex-channels at `760px`, and neither number has a reason.
 *
 * It folds *whole* rather than progressively, unlike `Toolbar`:
 * `Toolbar`'s items are ranked, and a nav's order is the shape of
 * the product (Docket's reads as the pipeline: Triage → Backlog →
 * Phases → Board → Archives). Half of that behind a button is a rule
 * no reader can learn.
 *
 * ⚠️ **A `bar` must not be sized by its own contents.** It measures
 * its own box to decide what to draw in it, so a container that
 * shrink-wraps makes the answer its own input: put it in a
 * `minmax(0, 1fr)` grid track or a `flex-1 min-w-0` row. The root
 * carries `min-w-0 flex-1` for the flex case; a grid track is the
 * caller's to declare.
 *
 * ## `menu` is the rail's narrow state, and the app owns it
 *
 * `bar` builds its own trigger because it knows when it folded.
 * `menu` takes one, because the rail's narrow state puts that
 * control in the `Header` — a different corner of `Shell`'s grid
 * from a side rail, and no media query moves an element across a
 * grid. `useNavLayout` is what tells the app which of the two it is
 * rendering.
 *
 * ## Mounted exactly once
 *
 * A destination is in the bar or in the panel, never both. The
 * fleet's habit is to render the whole nav twice and hide one copy
 * with `hidden md:flex` — mux-magic's `PageHeader` across two
 * ~55-line blocks, mail-sifter's `TriageQueue` again — which puts
 * every link in the DOM at every width, so an agent driving the page
 * finds two of each and cannot tell which one a human can see.
 */
export declare const Nav: (props: NavProps) => ReactNode;
export {};
//# sourceMappingURL=Nav.d.ts.map