@nxgt/material 3.79.1 → 3.80.0

package/dist/lib/components/ui/layout/app-bar/top-app-bar.d.ts

@@ -1,3 +1,18 @@
-import { ComponentProps } from 'react';
-export type TopAppBarProps = {} & ComponentProps<'div'>;
-export declare function TopAppBar({ className, ...props }: TopAppBarProps): import("react").JSX.Element;
+import { ComponentProps, ReactNode } from 'react';
+export type TopAppBarProps = {
+    /**
+     * The bar's look. `'small'` (the default): one row of `children`.
+     * `'center'`: the row's content centred. `'medium'` and `'large'`: the
+     * `headline` on a second row, in display type (`'large'` a taller row and a
+     * bigger step); without a `headline` they draw as `'small'`.
+     */
+    variant?: 'small' | 'center' | 'medium' | 'large';
+    /** The title of a `medium` or `large` bar: its second row. Make it the page's heading with an element of your own, `<h1>`. */
+    headline?: ReactNode;
+} & ComponentProps<'div'>;
+/**
+ * A top app bar: a row of actions and a title, in the Material 3 sizes. It
+ * does not scroll itself; `ActivityLayout`'s `header` collapses and hides the
+ * shell's own bar.
+ */
+export declare function TopAppBar({ variant, headline, className, children, ...props }: TopAppBarProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/app-search-bar.d.ts

@@ -0,0 +1,11 @@
+import { AppSearchBarProps } from './app-search.types.js';
+/**
+ * The search of the app bar. From 768px a pill (a filled, fully rounded
+ * search field) with the `results` in a panel docked under it while it is
+ * focused or typed in; on a phone a search button that opens the full-screen
+ * {@link SearchView}. The text is shared by the two, so a resize keeps it.
+ *
+ * Draw it in the shell with `ActivityLayout`'s `header={{ variant, search }}`
+ * (or a route's `handle.header`), or put it in your own bar.
+ */
+export declare function AppSearchBar({ value: valueProp, defaultValue, onValueChange, ...props }: AppSearchBarProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/app-search.types.d.ts

@@ -0,0 +1,47 @@
+import { ReactNode } from 'react';
+/** What a `results` function receives. */
+export type SearchResultsState = {
+    /** The text typed so far. */
+    value: string;
+    /** Closes the panel (desktop) or the full-screen view (phone): call it when a result is chosen. */
+    close: () => void;
+};
+/** What the search bar and the full-screen view share. */
+export type AppSearchSlots = {
+    /** The field's placeholder. @default 'Search' (`material.search-field.placeholder`) */
+    placeholder?: string;
+    /** The search's accessible name: the field's, the phone button's and the view's. @default 'Search' (`material.app-header.search`) */
+    label?: string;
+    /** Enter in the field. The phone's view closes after it; the desktop's panel too. */
+    onSubmit?: (value: string) => void;
+    /**
+     * The results, drawn below the field: in a docked panel under the pill from
+     * 768px, in the full-screen view below it. A node, or a function of the
+     * text and a `close`. Unset: no panel on desktop, an empty view on a phone.
+     */
+    results?: ReactNode | ((state: SearchResultsState) => ReactNode);
+    /** How many results there are: announced politely ("3 results") whenever it changes. Unset: nothing is announced. */
+    resultCount?: number;
+    /** A spinner in the field instead of the clear button. @default false */
+    loading?: boolean;
+    /** Controls after the field: a filters button, in the bar beside the pill and in the phone's view. */
+    trailing?: ReactNode;
+};
+export type AppSearchBarProps = AppSearchSlots & {
+    /** Controls the text. */
+    value?: string;
+    /** The text to start from when `value` is unset. @default '' */
+    defaultValue?: string;
+    /** Asked for every change of the text, controlled or not. */
+    onValueChange?: (value: string) => void;
+    /**
+     * A hint for the key that focuses the pill (opens the view on a phone), such
+     * as `"/"` or `"Ctrl+K"`: shown as a `Kbd` while the field is empty and set
+     * as `aria-keyshortcuts`, and bound on the document (ignored while typing in
+     * another field).
+     */
+    shortcut?: string;
+    /** Controls before the pill (desktop only). */
+    leading?: ReactNode;
+    className?: string;
+};

package/dist/lib/components/ui/layout/app-search/index.d.ts

@@ -0,0 +1,3 @@
+export type { AppSearchBarProps, AppSearchSlots, SearchResultsState, } from './app-search.types.js';
+export { AppSearchBar } from './app-search-bar.js';
+export { SearchView, type SearchViewProps } from './search-view.js';

package/dist/lib/components/ui/layout/app-search/partials/on-phone.d.ts

@@ -0,0 +1,2 @@
+/** Whether the viewport is a phone's, asked when a key is pressed (never while rendering). */
+export declare const onPhone: () => boolean;

package/dist/lib/components/ui/layout/app-search/partials/phone-search.d.ts

@@ -0,0 +1,3 @@
+import { AppSearchBarProps } from '../app-search.types.js';
+/** The phone half of the search: a button (hidden from 768px) that opens the full-screen view. */
+export declare function PhoneSearch({ value: valueProp, defaultValue, onValueChange, shortcut, leading: _leading, className, ...slots }: AppSearchBarProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/partials/pill-search.d.ts

@@ -0,0 +1,3 @@
+import { AppSearchBarProps } from '../app-search.types.js';
+/** The tablet and desktop half of the search: the pill and its results panel (hidden below 768px). */
+export declare function PillSearch({ value: valueProp, defaultValue, onValueChange, shortcut, leading, trailing, className, placeholder, label, onSubmit, results, resultCount, loading, }: AppSearchBarProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/pill-form.d.ts

@@ -0,0 +1,18 @@
+import { KeyboardEvent } from 'react';
+import { AppSearchBarProps } from './app-search.types.js';
+/**
+ * The pill's field in a named search landmark. `onActivate` hears a click or
+ * a focus inside it (`true` for a focus), which is what opens the panel.
+ */
+export declare function PillForm({ name, value, onValueChange, placeholder, shortcut, loading, onSubmit, onKeyDown, onActivate, panelId, panelOpen, hasPanel, }: Pick<AppSearchBarProps, 'placeholder' | 'shortcut' | 'loading'> & {
+    name: string;
+    value: string;
+    onValueChange: (value: string) => void;
+    onSubmit: () => void;
+    onKeyDown: (event: KeyboardEvent<HTMLFormElement>) => void;
+    onActivate: (byFocus: boolean) => void;
+    /** The results panel's id, and whether there is one and it is open: the field announces it. */
+    panelId: string;
+    panelOpen: boolean;
+    hasPanel: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/search-panel.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode, RefObject } from 'react';
+/**
+ * The pill's docked results panel: a non-modal popover under the pill, as wide
+ * as it. Focus stays in the field; ArrowDown moves into the panel and Escape
+ * brings it back to the field (the panel renders in a portal, which Tab does
+ * not reach from the field).
+ */
+export declare function SearchPanel({ open, onOpenChange, anchor, barRef, barClassName, focusField, panelId, children, panelRef, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** The pill: the panel opens under it, and a pointer or focus inside it does not dismiss the panel. */
+    anchor: ReactNode;
+    /** The element the panel hangs from (the bar around the pill). */
+    barRef: RefObject<HTMLDivElement | null>;
+    barClassName?: string;
+    /** Puts the focus back in the field, without opening the panel again. */
+    focusField: () => void;
+    /** The panel's id, for the field's `aria-controls`. */
+    panelId: string;
+    children: ReactNode;
+    panelRef: RefObject<HTMLDivElement | null>;
+}): import("react").JSX.Element;
+/** Focuses the first control in the panel; whether there was one. */
+export declare function focusPanel(panel: HTMLElement | null): boolean;

package/dist/lib/components/ui/layout/app-search/search-results.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { AppSearchSlots } from './app-search.types.js';
+/** The `results` slot drawn: a node as it is, a function called with the text and `close`. */
+export declare function drawResults(results: AppSearchSlots['results'], state: {
+    value: string;
+    close: () => void;
+}): ReactNode;
+/**
+ * The polite announcement of how many results there are. Always in the tree
+ * with the results, so a screen reader hears the change, not an insertion.
+ */
+export declare function ResultCount({ count }: {
+    count?: number;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/search-shortcut.d.ts

@@ -0,0 +1,15 @@
+type KeyLike = Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>;
+/**
+ * Whether a key event is the `shortcut` ("/", "Ctrl+K", "Alt+S", "mod+k":
+ * `mod` is Ctrl or Cmd). A bare character ignores Shift, which typing it may
+ * need; the named modifiers must match exactly.
+ */
+export declare function matchesShortcut(event: KeyLike, shortcut?: string): boolean;
+/**
+ * Runs `onKey` when the document gets the `shortcut`. A bare key does nothing
+ * while the focus is in a field; one with Ctrl, Cmd or Alt works anywhere.
+ * `when` is asked first: a bar drawn twice (the phone's button and the pill,
+ * one hidden by CSS) lets only the visible one take the key.
+ */
+export declare function useSearchShortcut(shortcut: string | undefined, onKey: () => void, when?: () => boolean): void;
+export {};

package/dist/lib/components/ui/layout/app-search/search-view.d.ts

@@ -0,0 +1,22 @@
+import { AppSearchSlots } from './app-search.types.js';
+export type SearchViewProps = AppSearchSlots & {
+    /** Whether the view is open. It mounts only while open, so the server draws nothing. */
+    open: boolean;
+    /** Asked for every change: Escape, the back arrow, Enter in the field. */
+    onOpenChange: (open: boolean) => void;
+    /** Controls the text. */
+    value?: string;
+    /** The text to start from when `value` is unset. @default '' */
+    defaultValue?: string;
+    /** Asked for every change of the text, controlled or not. */
+    onValueChange?: (value: string) => void;
+};
+/**
+ * The phone's search: a full-screen modal dialog named by `label`, with a
+ * back arrow, the search field and the `results` below it. Focus goes to the
+ * field when it opens and returns to the element that opened it when it
+ * closes; Escape (after the clear, if the field holds text) and the back
+ * arrow close it. `AppSearchBar` opens it from a phone; use it on its own
+ * for a search button of your own.
+ */
+export declare function SearchView({ open, onOpenChange, value: valueProp, defaultValue, onValueChange, placeholder, label, onSubmit, results, resultCount, loading, trailing, }: SearchViewProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-search/use-pill-panel.d.ts

@@ -0,0 +1,22 @@
+import { KeyboardEvent } from 'react';
+/**
+ * The state of the pill's results panel: open or not, the refs it hangs from,
+ * and the keyboard (ArrowDown opens it, then moves into it). Focus the code
+ * gives the field (`focusField`, the shortcut) is not a reason to open it.
+ */
+export declare function usePillPanel(hasResults: boolean): {
+    panel: boolean;
+    setPanel: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    bar: import('react').RefObject<HTMLDivElement | null>;
+    panelRef: import('react').RefObject<HTMLDivElement | null>;
+    panelId: string;
+    open: () => void;
+    close: () => void;
+    /** Puts the focus back in the field, without opening the panel. */
+    focusField(): void;
+    /** Focuses the field as the shortcut does: it does open nothing. */
+    focusFromShortcut(): void;
+    /** A click, or a focus unless the code gave it. */
+    activate(byFocus: boolean): void;
+    onKeyDown(event: KeyboardEvent<HTMLElement>): void;
+};

package/dist/lib/components/ui/layout/app-search/use-search-text.d.ts

@@ -0,0 +1,8 @@
+type Options = {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+};
+/** The text of a search, controlled (`value`) or not, reporting every change. */
+export declare function useSearchText({ value, defaultValue, onValueChange, }: Options): readonly [string, (next: string) => void];
+export {};

package/dist/lib/components/ui/layout/app-shell/activity-app-bar.d.ts

@@ -0,0 +1,35 @@
+import { ComponentProps, ReactNode, RefObject } from 'react';
+import { ShellBack } from './activity-layout-navigation.types.js';
+import { AppHeader } from './app-header.js';
+import { ResolvedHeader } from './navigation.utils.js';
+import { usePageTitleScope } from './page-title-scope.js';
+type BarProps = ReturnType<typeof usePageTitleScope>;
+/** Whether the header has a headline row: a medium or large one, with a page title to put in it. */
+export declare const hasHeadline: (header: ResolvedHeader, pageTitle: ReactNode) => boolean;
+/** Whether the shell's scroll has to be tracked: a bar that collapses or hides. */
+export declare const scrollsHeader: (header: ResolvedHeader, pageTitle: ReactNode) => boolean;
+/**
+ * Provides the scroll of the window, or of the content region (`region`), to
+ * the bar below. The provider is always in the tree, so a route that changes
+ * the header never remounts the content; with `on` false it tracks nothing
+ * (no listener, no frame), so a plain shell adds no scroll work.
+ */
+export declare function ActivityScroll({ on, region, children, }: {
+    on: boolean;
+    region: RefObject<HTMLElement | null> | null;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The app bar of {@link ActivityLayout}, in the header variant the route
+ * resolved: a headline row carries the page's `h1` for `medium` and `large`
+ * (the small row then holds a faded copy of it), the other variants keep it in
+ * the bar.
+ */
+export declare function ActivityAppBar({ header, back, bar, headerTitle, hasBackdrop, ...props }: {
+    header: ResolvedHeader;
+    back?: ShellBack;
+    bar: BarProps;
+    headerTitle?: ReactNode;
+    hasBackdrop: boolean;
+} & Omit<ComponentProps<typeof AppHeader>, 'children' | 'variant' | 'headline'>): import("react").JSX.Element | null;
+export {};

package/dist/lib/components/ui/layout/app-shell/activity-chrome.d.ts

@@ -1,10 +1,17 @@
 import { ReactNode } from 'react';
+import { NavigationRailProps } from '../navigation-rail/navigation-rail.js';
 import { AppSidebarProps } from './app-sidebar.js';
 /** Under a `backdrop`: the chrome's fill, from a token (activity-backdrop.css). */
 export declare const CHROME_FILL = "bg-(--nxgt-backdrop-fill-chrome)";
 /** The app bar: that fill, frosted (the blur is 0 when the user asks for less
  * transparency). */
 export declare const CHROME_FROSTED = "bg-(--nxgt-backdrop-fill-chrome) backdrop-blur-(--nxgt-backdrop-blur)";
+/**
+ * The sticky app bar's classes: translucent under a `backdrop` (the fill is a
+ * token, activity-backdrop.css), flat like the sidebar (no radius, no shadow,
+ * near --background).
+ */
+export declare const appBarClass: (hasBackdrop: boolean) => string;
 /** The sidebar: a little more opaque than the app bar, for its text's contrast. */
 export declare const NAV_FROSTED = "bg-(--nxgt-backdrop-fill-nav) backdrop-blur-(--nxgt-backdrop-blur)";
 /**
@@ -13,7 +20,7 @@ export declare const NAV_FROSTED = "bg-(--nxgt-backdrop-fill-nav) backdrop-blur-
  * media dock at the bottom) with a negative margin and gives it to itself as
  * padding, so the sticky sidebar rests where it always did.
  */
-export declare const RAIL_BLEED = "-mt-[max(0.5rem,env(safe-area-inset-top))] pt-[max(0.5rem,env(safe-area-inset-top))] -mb-[calc(max(0.5rem,env(safe-area-inset-bottom))+var(--nxgt-media-dock,0px))] pb-[calc(max(0.5rem,env(safe-area-inset-bottom))+var(--nxgt-media-dock,0px))] -ml-[max(0.5rem,env(safe-area-inset-left))] pl-[max(0.5rem,env(safe-area-inset-left))]";
+export declare const RAIL_BLEED = "-mt-[max(0.5rem,env(safe-area-inset-top))] pt-[max(0.5rem,env(safe-area-inset-top))] -mb-[max(max(0.5rem,env(safe-area-inset-bottom)),calc(0.5rem+var(--nxgt-media-dock,0px)))] pb-[max(max(0.5rem,env(safe-area-inset-bottom)),calc(0.5rem+var(--nxgt-media-dock,0px)))] -ml-[max(0.5rem,env(safe-area-inset-left))] pl-[max(0.5rem,env(safe-area-inset-left))]";
 /**
  * The top gutter, above the sticky app bar, stays in the viewport and hides
  * what the page scrolls under it: the app bar's own fill, so nothing shows in
@@ -24,18 +31,34 @@ export declare const RAIL_BLEED = "-mt-[max(0.5rem,env(safe-area-inset-top))] pt
 export declare function ActivityGutterMask({ hasBackdrop }: {
     hasBackdrop: boolean;
 }): import("react").JSX.Element;
+/** A lane sticks below the notch and is as tall as the viewport, clear of the home indicator and a docked player. A whole literal, so Tailwind sees it. */
+export declare const LANE_STICKY = "sticky top-[max(0.5rem,env(safe-area-inset-top))] h-[calc(100dvh-max(0.5rem,env(safe-area-inset-top))-max(max(0.5rem,env(safe-area-inset-bottom)),calc(0.5rem+var(--nxgt-media-dock,0px))))] self-start";
 /**
  * The rail's lane: the fill runs the whole height of the page (the sidebar
  * itself is sticky and only as tall as the viewport), out to the frame's edges.
  * Translucent under a `backdrop`: the fill is a token (activity-backdrop.css).
  * Flat, on the page's own colour: no radius, no shadow.
  */
-export declare function ActivityRail({ hasBackdrop, ...sidebar }: {
+export declare function ActivityRail({ hasBackdrop, hide, ...sidebar }: {
     hasBackdrop: boolean;
+    /** The classes hiding the rail at the sizes it does not show. */
+    hide?: string;
 } & Pick<AppSidebarProps, 'items' | 'brand' | 'logo' | 'name' | 'linkComponent' | 'align'>): import("react").JSX.Element;
+/**
+ * The lane of the wide navigation rail (`navigation="rail-expanded"`), filled
+ * and bled to the frame's edges like {@link ActivityRail}'s. The rail itself
+ * sticks below the notch and is as tall as the viewport.
+ */
+export declare function ActivityNavRail({ hasBackdrop, hide, ...rail }: {
+    hasBackdrop: boolean;
+    /** The classes hiding the rail at the sizes it does not show. */
+    hide?: string;
+} & Pick<NavigationRailProps, 'items' | 'linkComponent' | 'fab' | 'defaultExpanded' | 'persistKey' | 'onExpandedChange'>): import("react").JSX.Element;
 /** The frame around the rail and the column, under the gutter mask (a page that scrolls itself needs one). */
-export declare function ActivityFrame({ contained, hasBackdrop, children, }: {
+export declare function ActivityFrame({ contained, hasBackdrop, bar, children, }: {
     contained: boolean;
     hasBackdrop: boolean;
+    /** Whether a bottom navigation bar is configured. */
+    bar?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-column-props.d.ts

@@ -0,0 +1,22 @@
+import { ActivityLayoutProps } from './activity-layout.types.js';
+declare const COLUMN_KEYS: readonly ["context", "headerTitle", "titleAfter", "headerContext", "breadcrumb", "breadcrumbRoot", "headerActions", "avatar", "menuOpen", "onMenuOpenChange", "keepClear"];
+type ColumnKey = (typeof COLUMN_KEYS)[number];
+export type ColumnOwnProps = Pick<ActivityLayoutProps, ColumnKey>;
+/**
+ * The props only the content column reads (its header, breadcrumb and
+ * clearing), apart from the rest: `ActivityLayout` hands them on without
+ * naming each, and the rest goes to the root element.
+ */
+export declare function splitColumnProps<P extends Partial<ColumnOwnProps>>(props: P): {
+    column: Partial<ColumnOwnProps>;
+    rest: Omit<P, ColumnKey>;
+};
+declare const RAIL_KEYS: readonly ["navigationFab", "sidebarExpanded", "defaultSidebarExpanded", "onSidebarExpandedChange"];
+type RailKey = (typeof RAIL_KEYS)[number];
+export type RailOwnProps = Pick<ActivityLayoutProps, RailKey>;
+/** The props only the navigation lanes read (the FAB, the sidebar's state), apart from the rest. */
+export declare function splitRailProps<P extends Partial<RailOwnProps>>(props: P): {
+    rails: RailOwnProps;
+    rest: Omit<P, RailKey>;
+};
+export {};

package/dist/lib/components/ui/layout/app-shell/activity-column.d.ts

@@ -1,17 +1,25 @@
 import { ReactNode } from 'react';
 import { ActivityLayoutProps } from './activity-layout.types.js';
-type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'titleAfter' | 'headerContext' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop' | 'keepClear'> & {
+type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'titleAfter' | 'headerContext' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop' | 'keepClear' | 'header'> & {
     /** The element of the content region. */
     as: 'main' | 'div';
     contained: boolean;
     /** Whether a backdrop is drawn, and whether it is the theme's. */
     hasBackdrop: boolean;
     themeBackdrop: boolean;
+    /** Whether the app bar has the phone's menu button. */
+    showMenu?: boolean;
+    /** The classes hiding the top navigation where it does not show; undefined: none in the header. */
+    topNav?: string;
+    /** The floating navigation toolbar, inside the scroll's provider so it reads the shell's scroll; it is fixed to the viewport. */
+    floating?: ReactNode;
+    /** Whether the shell's scroll is tracked for it (it hides on scroll). */
+    trackScroll?: boolean;
     children?: ReactNode;
 };
 /**
  * The content column of {@link ActivityLayout}: the backdrop layer behind, the
  * app bar, the breadcrumb and the routed content region.
  */
-export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, items, brand, logo, name, context, headerTitle, titleAfter, headerContext, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, menuOpen, onMenuOpenChange, routeTransition, backdrop, keepClear, children, }: ColumnProps): import("react").JSX.Element;
+export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, headerTitle, titleAfter, headerContext, breadcrumb, breadcrumbRoot, headerActions, avatar, routeTransition, backdrop, keepClear, showMenu, topNav, floating, trackScroll, header, children, ...menu }: ColumnProps): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/layout/app-shell/activity-layout-navigation.types.d.ts

@@ -0,0 +1,94 @@
+import { ReactNode } from 'react';
+import { AppSearchBarProps } from '../app-search/app-search.types.js';
+/**
+ * How the shell's navigation is drawn at one window size.
+ *
+ * The shell draws `'modal-drawer'` (the phone's menu sheet), `'rail'` (the
+ * collapsed sidebar rail), `'rail-expanded'` (the navigation rail, wide, with a
+ * menu button to narrow it; neither rail is drawn on a phone, which keeps its
+ * menu sheet), `'drawer'` (the permanent navigation drawer),
+ * `'sidebar'` (the sidebar, with a chevron button that expands and collapses it),
+ * `'top'` (the navigation bar in the app header, with dropdowns; not on a
+ * phone, which keeps its menu sheet and nests the children there),
+ * `'two-level'` (the navigation rail of the top-level entries and, beside it, a
+ * panel listing the current entry's children; not on a phone either),
+ * `'floating'` (the navigation toolbar: a pill of icon links at the bottom
+ * centre, over the content; unlike those it is drawn on a phone too, as the
+ * bar is), `'bar'` (the bottom bar: a name alone draws it on a phone only, and from
+ * 768px the default rail shows) and `'none'`.
+ */
+export type ShellNavigation = 'modal-drawer' | 'rail' | 'rail-expanded' | 'drawer' | 'sidebar' | 'bar' | 'top' | 'two-level' | 'floating' | 'none';
+/** The navigation per window size: phone below `md` (768px), tablet from `md` to `xl` (1280px), desktop from `xl`. */
+export type ShellNavigationOptions = {
+    /** Below 768px. @default 'modal-drawer' */
+    phone?: ShellNavigation;
+    /** From 768px to 1279px. @default 'rail' */
+    tablet?: ShellNavigation;
+    /** From 1280px. @default 'rail' */
+    desktop?: ShellNavigation;
+    /** Whether the `'floating'` toolbar slides away while scrolling down and comes back on the way up. No other preset reads it. @default false */
+    hideOnScroll?: boolean;
+    /** Keeps the `'rail-expanded'` rail's, the `'sidebar'`'s and the `'two-level'` panel's open or narrow state in the browser under this key (read after hydration). Unset: the rail starts expanded, the sidebar collapsed and the panel open every time. */
+    persistKey?: string;
+};
+/** The shell header's look. */
+export type ShellHeaderVariant = 'small' | 'center' | 'medium' | 'large' | 'none';
+/**
+ * A route's back arrow (`handle.back`): `{ to, label }` links to `to` and is
+ * named "Back to <label>" ("Back" without one); `true` goes back in the
+ * history, or up one level when the route is the first page of the visit.
+ */
+export type ShellBack = true | {
+    to: string;
+    label?: string;
+};
+/** The header, with its options. */
+export type ShellHeaderOptions = {
+    variant: ShellHeaderVariant;
+    /** Whether a `medium` or `large` header collapses to the small one while scrolling. @default true for 'medium' and 'large' */
+    collapse?: boolean;
+    /** Whether the header slides away while scrolling down. @default false */
+    hideOnScroll?: boolean;
+    /**
+     * Tabs under the header: a `TabsNav` (route links). The row is stuck to the
+     * bar: it stays under a `medium` or `large` one as it collapses, and stays
+     * pinned at the top of the window when `hideOnScroll` slides the bar away.
+     * A route's `handle.header.tabs` replaces the layout's; `tabs: null` drops
+     * them for that route. A header of `'none'` draws none.
+     * @default undefined (no tabs)
+     */
+    tabs?: ReactNode;
+    /**
+     * A search in the app bar: a pill from 768px, a button opening a full-screen
+     * view on a phone (`AppSearchBar`). `true`: an uncontrolled one with no
+     * results; an object sets its props (`value`, `onSubmit`, `results`…).
+     * @default undefined (no search)
+     */
+    search?: boolean | AppSearchBarProps;
+};
+/** The props `ActivityLayout` takes to choose its navigation and its header. */
+export type ActivityLayoutNavigationProps = {
+    /**
+     * The navigation: one preset for every window size, or one per size.
+     * Unset: the phone's menu sheet (`'modal-drawer'`), the rail from 768px.
+     */
+    navigation?: ShellNavigation | ShellNavigationOptions;
+    /**
+     * The header: a variant, or the variant with its options. Unset: `'small'`.
+     */
+    header?: ShellHeaderVariant | ShellHeaderOptions;
+    /**
+     * The screen's primary action, drawn at the top of the `'rail-expanded'`
+     * rail: a `Fab`, or a function that receives `{ expanded }` to pass an
+     * extended one. Not drawn by the other presets.
+     */
+    navigationFab?: ReactNode | ((state: {
+        expanded: boolean;
+    }) => ReactNode);
+    /** Controls the `'sidebar'`: expanded (labels beside the icons) while true. */
+    sidebarExpanded?: boolean;
+    /** The `'sidebar'`'s state to start from, before a saved choice (`navigation.persistKey`) is read. @default false */
+    defaultSidebarExpanded?: boolean;
+    /** Asked for every change of the `'sidebar'`'s state, controlled or not. */
+    onSidebarExpandedChange?: (expanded: boolean) => void;
+};

package/dist/lib/components/ui/layout/app-shell/activity-layout.d.ts

@@ -14,5 +14,12 @@ export type { ActivityLayoutProps } from './activity-layout.types.js';
  * scrollbar (a page a few pixels too wide) and `100lvh` the height behind a
  * phone's toolbar (the bottom of the screen hidden). The bottom keeps clear
  * of a `MediaPlayerHost`'s docked bar (`--nxgt-media-dock`).
+ *
+ * `navigation` is resolved by resolveNavigation(): the presets drawn so far are
+ * the modal drawer, the rail, the wide rail, the sidebar, the drawer, the top
+ * bar, the two-level navigation, the floating toolbar, the bar and none; the others draw what their size has by default.
+ * `header` is resolved in the column, with the route's `handle.header`: its
+ * variants and its `search` and `tabs` are drawn; the route's `handle.back` draws a back
+ * arrow.
  */
-export declare function ActivityLayout({ items, brand, logo, name, context, headerTitle, titleAfter, headerContext, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, contentAs: Content, scroll, align, menuOpen, onMenuOpenChange, routeTransition, backdrop, keepClear, children, className, ...props }: ActivityLayoutProps): import("react").JSX.Element;
+export declare function ActivityLayout({ items, brand, logo, name, linkComponent, contentAs: Content, scroll, align, routeTransition, backdrop, navigation, header, children, className, ...others }: ActivityLayoutProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-layout.types.d.ts

@@ -1,4 +1,5 @@
 import { ComponentProps, ReactNode } from 'react';
+import { ActivityLayoutNavigationProps } from './activity-layout-navigation.types.js';
 import { AppBreadcrumbRoot } from './app-breadcrumb.js';
 import { RouteTransition } from './route-transition.js';
 import { AppLogo, AppShellLinkComponent, MenuItem } from './types.js';
@@ -141,4 +142,4 @@ export type ActivityLayoutProps = {
      * See the app shell guide, "Keep the backdrop clear of the content".
      */
     keepClear?: boolean | 'gaps';
-} & ComponentProps<'div'>;
+} & ActivityLayoutNavigationProps & ComponentProps<'div'>;

package/dist/lib/components/ui/layout/app-shell/activity-rails.d.ts

@@ -0,0 +1,16 @@
+import { RailOwnProps } from './activity-column-props.js';
+import { ActivityLayoutProps } from './activity-layout.types.js';
+import { ShellParts } from './navigation-parts.js';
+/**
+ * The navigation lanes before the column: the collapsed sidebar rail
+ * (`'rail'`), the collapsible sidebar (`'sidebar'`), the permanent drawer
+ * (`'drawer'`), the two-level rail and panel (`'two-level'`) and the wide
+ * navigation rail (`'rail-expanded'`), each hidden by breakpoint classes where its size has
+ * another preset.
+ */
+export declare function ActivityRails({ parts, items, brand, logo, name, linkComponent, hasBackdrop, align, rails, }: Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'linkComponent' | 'align'> & {
+    /** The FAB and the `'sidebar'` lane's state props. */
+    rails: RailOwnProps;
+    parts: ShellParts;
+    hasBackdrop: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-sidebar-lane.d.ts

@@ -0,0 +1,22 @@
+import { ActivityLayoutProps } from './activity-layout.types.js';
+import { AppSidebarProps } from './app-sidebar.js';
+/** The key the sidebar's state is kept under, beside the rail's. */
+export declare const SIDEBAR_STORAGE_PREFIX = "nxgt-sidebar:";
+type LaneProps = {
+    hasBackdrop: boolean;
+    /** The classes hiding the lane at the sizes it does not show. */
+    hide?: string;
+};
+/** The lane of the permanent navigation drawer (`navigation="drawer"`), filled and bled to the frame's edges like the rail's. */
+export declare function ActivityDrawerLane({ hasBackdrop, hide, ...drawer }: LaneProps & Pick<ActivityLayoutProps, 'items' | 'linkComponent'> & Pick<AppSidebarProps, 'brand'>): import("react").JSX.Element;
+/**
+ * The lane of the collapsible sidebar (`navigation="sidebar"`): the app's
+ * sidebar, with a chevron button on its end edge that collapses it to icons and expands
+ * it again. The state is `sidebarExpanded` (controlled) or
+ * `defaultSidebarExpanded` (collapsed), and with a `persistKey` the last choice is read
+ * after hydration.
+ */
+export declare function ActivitySidebarLane({ hasBackdrop, hide, persistKey, sidebarExpanded, defaultSidebarExpanded, onSidebarExpandedChange, align, ...sidebar }: LaneProps & Pick<ActivityLayoutProps, 'sidebarExpanded' | 'defaultSidebarExpanded' | 'onSidebarExpandedChange'> & Pick<AppSidebarProps, 'items' | 'brand' | 'logo' | 'name' | 'linkComponent' | 'align'> & {
+    persistKey?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/layout/app-shell/activity-top-nav.d.ts

@@ -0,0 +1,11 @@
+import { ActivityLayoutProps } from './activity-layout.types.js';
+/**
+ * The top navigation in the app header (`navigation="top"`): the app's brand,
+ * which no rail carries then, and the bar of destinations. Hidden by
+ * breakpoint classes at the sizes that have another preset, so the server and
+ * the browser draw the same markup.
+ */
+export declare function ActivityTopNav({ items, brand, logo, name, linkComponent, hide, }: Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'linkComponent'> & {
+    /** The classes hiding the bar at the sizes it does not show; undefined: no top navigation. */
+    hide?: string;
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/layout/app-shell/activity-two-level-lane.d.ts

@@ -0,0 +1,14 @@
+import { ActivityLayoutProps } from './activity-layout.types.js';
+/**
+ * The lane of the two-level navigation (`navigation="two-level"`): the
+ * navigation rail with the top-level entries, then the section panel listing
+ * the current entry's children, filled and bled to the frame's edges like the
+ * other lanes. The panel is open by default and folds to a button; with a
+ * `persistKey` its state is remembered under `nxgt-panel:<key>`.
+ */
+export declare function ActivityTwoLevelLane({ items, brand, logo, name, linkComponent, hasBackdrop, hide, persistKey, }: Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'linkComponent'> & {
+    hasBackdrop: boolean;
+    /** The classes hiding the lane at the sizes it does not show. */
+    hide?: string;
+    persistKey?: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/app-back.d.ts

@@ -0,0 +1,22 @@
+import { ShellBack } from './activity-layout-navigation.types.js';
+import { AppShellLinkComponent } from './types.js';
+/**
+ * The path one level up: `/projects/atlas` is `/projects`, `/projects` is
+ * `/`.
+ */
+export declare const parentPath: (pathname: string) => string;
+/**
+ * The route's back arrow (`handle.back`), at the start of the app bar: a 48px
+ * target named "Back" or "Back to <label>".
+ *
+ * `{ to }` is a link, drawn with the shell's link component (React Router's by
+ * default), so it can be opened in a new tab. `true` is a button: the
+ * history's previous entry when the visit has one (`location.key` is not
+ * `'default'`), the parent path (`parentPath`: the URL minus its last
+ * segment) when this page opened the visit, so the arrow never leaves the
+ * app.
+ */
+export declare function AppBack({ back, linkComponent, }: {
+    back: ShellBack;
+    linkComponent?: AppShellLinkComponent;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/app-header-row.d.ts

@@ -0,0 +1,3 @@
+import { AppHeaderProps } from './app-header.js';
+/** The bar's one row: the menu, the top navigation, the titles, the actions and the account. */
+export declare function AppHeaderRow({ items, linkComponent, children, topNav, actions, avatar, search, back, brand, logo, name, context, menuOpen, onMenuOpenChange, showMenuIcon, }: Omit<AppHeaderProps, 'className' | 'variant' | 'collapse' | 'hideOnScroll' | 'headline' | 'tabs'>): import("react").JSX.Element;