@nxgt/material 3.85.1 → 3.86.0

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

@@ -1,2 +1,2 @@
 export * from './bottom-app-bar.js';
-export * from './top-app-bar.js';
+export * from './top-app-bar/index.js';

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

@@ -0,0 +1 @@
+export * from './top-app-bar.js';

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

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { LinkComponent } from '../../../../primitives/link/link-component.js';
+import { TopAppBarAction } from '../top-app-bar.types.js';
+/**
+ * The bar's `actions` array: free ghost icon buttons, `between` (the primary
+ * action), then the account menu (on `trailing`, or a More button) with the
+ * rest. A phone and a desktop share one markup; classes hide what each does
+ * not show.
+ */
+export declare function TopAppBarActions({ actions, trailing, linkComponent, between, }: {
+    actions: readonly TopAppBarAction[];
+    trailing?: ReactNode;
+    linkComponent?: LinkComponent;
+    between?: ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+import { ComponentProps } from 'react';
+import { TopAppBarTitleBlock } from './top-app-bar-title-block.js';
+/** The second row of a medium or large bar: the title block, with room under it. */
+export declare function TopAppBarHeadline(props: ComponentProps<typeof TopAppBarTitleBlock>): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import { ElementType } from 'react';
+import { LinkComponent } from '../../../../primitives/link/link-component.js';
+/** The classes that hide an entry on the screen that does not show it. */
+export declare const ONLY: {
+    readonly phone: "md:hidden";
+    readonly desktop: "max-md:hidden";
+};
+/** The link an action with an `href` renders: the prop, the provider's, else `a`. */
+export declare function useLink(own?: LinkComponent): ElementType;

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

@@ -0,0 +1,14 @@
+import { LinkComponent } from '../../../../primitives/link/link-component.js';
+import { PlacedAction } from '../top-app-bar.actions.js';
+/**
+ * The separator before section `i` belongs to it: hidden on a screen where
+ * that section is hidden, or where every section before it is.
+ */
+export declare function separatorClass(sections: {
+    items: PlacedAction[];
+}[], i: number): string;
+export declare function MenuSection({ group, items, linkComponent, }: {
+    group?: string;
+    items: PlacedAction[];
+    linkComponent?: LinkComponent;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { TopAppBarPrimaryAction } from '../top-app-bar.types.js';
+/**
+ * The screen's main action. A `Button` in the row from 768 px and a `Fab` in
+ * the `FabDock` (above `--nxgt-bottom-chrome`) on a phone. Both are in the
+ * markup and only CSS hides one: the page renders the same on the server for
+ * every width, so a screen reader or a test sees the name twice in the DOM
+ * but one of the two is `display: none`. After mount the dock moves to
+ * `document.body`, out of any transformed ancestor.
+ */
+export declare function TopAppBarPrimary({ action, }: {
+    action: TopAppBarPrimaryAction;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+import { LinkComponent } from '../../../../primitives/link/link-component.js';
+import { TopAppBarAction, TopAppBarPrimaryAction } from '../top-app-bar.types.js';
+type Props = {
+    leading?: ReactNode;
+    /** The shell's leading title, drawn in one box with the titles. */
+    titleLead?: ReactNode;
+    /** The title block, or nothing on a medium or large bar. */
+    title?: ReactNode;
+    /** A medium or large bar that collapses: the title's copy for the eye, shown in this row once the headline has folded away. */
+    collapsedTitle?: ReactNode;
+    titleAfter?: ReactNode;
+    search?: ReactNode;
+    children?: ReactNode;
+    actions?: ReactNode | TopAppBarAction[];
+    primaryAction?: TopAppBarPrimaryAction;
+    linkComponent?: LinkComponent;
+    trailing?: ReactNode;
+    collapsedSlot?: string;
+};
+/** The bar's first row: leading, title, the app's own children, actions, trailing. */
+export declare function TopAppBarRow({ leading, titleLead, title, collapsedTitle, titleAfter, search, children, actions, primaryAction, linkComponent, trailing, collapsedSlot, }: Props): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { TopAppBarSlotNames } from '../top-app-bar.types.js';
+type Props = {
+    title: ReactNode;
+    titleId?: string;
+    subtitle?: ReactNode;
+    /** The old `headline`: the app's own element, so no second `<h1>`. */
+    legacy?: boolean;
+    slotNames?: TopAppBarSlotNames;
+};
+/**
+ * The one `<h1>` and, right after it (not inside), the subtitle `<p>`. Each
+ * carries a `title` with its full text only once it is cut off by an ellipsis
+ * (#629); the `<h1>` is focusable by script (never by Tab), so a shell can
+ * start a new page at its name.
+ */
+export declare function TopAppBarTitleBlock({ title, titleId, subtitle, legacy, slotNames, }: Props): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,43 @@
+import { TopAppBarAction } from './top-app-bar.types.js';
+/** The icons the bar keeps: one on a phone, two from 768 px. */
+export declare const BAR_ICONS_PHONE = 1;
+export declare const BAR_ICONS_DESKTOP = 2;
+/** On which screens an entry shows, when it is not on both. */
+export type ActionScreen = 'phone' | 'desktop';
+export type PlacedAction = {
+    action: TopAppBarAction;
+    /** The key: the action's `id`, else its `label`. */
+    key: string;
+    /** Absent: both screens. */
+    only?: ActionScreen;
+};
+export type PartitionedActions = {
+    /** The bar's icons; a `only: 'desktop'` one is hidden on a phone. */
+    bar: PlacedAction[];
+    /** The menu's entries, in the given order; a `only: 'phone'` one is the bar icon a phone gave up. */
+    menu: PlacedAction[];
+};
+/**
+ * Splits the actions between the bar's free icons and the account menu, for
+ * both screens at once (a phone and a desktop share one markup, so the page
+ * renders the same on the server). The first `'bar'` actions fill the
+ * icons (`phone` of them on a phone, `desktop` from 768 px); a `'bar'` action
+ * that does not fit goes to the menu; an `'account'` one is always in it.
+ */
+export declare function partitionActions(actions: readonly TopAppBarAction[], limits?: {
+    phone?: number;
+    desktop?: number;
+}): PartitionedActions;
+/** The menu's entries cut into labelled sections: the ungrouped ones first, then each group in order of appearance. */
+export declare function groupMenu(menu: readonly PlacedAction[]): {
+    group?: string;
+    items: PlacedAction[];
+}[];
+/** The one screen every entry of a section is limited to, else undefined (it shows on both). */
+export declare function sectionScreen(items: readonly PlacedAction[]): ActionScreen | undefined;
+/**
+ * Whether `actions` is data: a non-empty array whose every item is a plain
+ * object with a string `label`. An array of elements (keyed buttons) is a
+ * node and is drawn as given.
+ */
+export declare function isActionData(actions: unknown): actions is TopAppBarAction[];

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

@@ -0,0 +1,9 @@
+import { TopAppBarProps } from './top-app-bar.types.js';
+export type { TopAppBarAction, TopAppBarActionPlacement, TopAppBarAlign, TopAppBarPrimaryAction, TopAppBarProps, TopAppBarSize, } from './top-app-bar.types.js';
+/**
+ * A top app bar: a row of actions and a title, in the Material 3 sizes. It
+ * is flat on the page ground; a `data-scrolled` attribute (set by the shell)
+ * tints it and draws a hairline. It does not scroll itself; `ActivityLayout`'s
+ * `header` collapses and hides the shell's own bar.
+ */
+export declare function TopAppBar({ size: sizeProp, align: alignProp, variant, title: titleProp, headline, titleId, subtitle, titleAfter, leading, actions, primaryAction, linkComponent, trailing, search, tabs, collapse, hideOnScroll, slotNames, titleLead, as: Tag, className, children, ...props }: TopAppBarProps): import("react").JSX.Element;

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

@@ -0,0 +1,120 @@
+import { ComponentProps, ReactNode } from 'react';
+import { LinkComponent } from '../../../primitives/link/link-component.js';
+/** How tall the bar is: one row, a second row for the title, or a search field. */
+export type TopAppBarSize = 'small' | 'medium-flexible' | 'large-flexible' | 'search';
+/** Where a `small` bar puts its title. */
+export type TopAppBarAlign = 'start' | 'center';
+/** Where an action of a `TopAppBarAction[]` goes: a free icon in the bar, or the account menu. */
+export type TopAppBarActionPlacement = 'bar' | 'account';
+/**
+ * One action of the bar, as data: a free ghost icon button in the bar, or an
+ * entry of the account menu. The bar keeps one icon on a phone and two from
+ * 768 px; the rest goes to the menu.
+ */
+export type TopAppBarAction = {
+    /** The key; defaults to `label`. */
+    id?: string;
+    /** The action's name: the icon button's accessible name, the menu entry's text. */
+    label: string;
+    /** The icon, decorative (the action is named by `label`). */
+    icon?: ReactNode;
+    /** The action was chosen. */
+    onClick?: () => void;
+    /** Makes the action a link, drawn with `linkComponent` (default `<a>`). */
+    href?: string;
+    /** `'bar'` (default): a bar icon while there is room. `'account'`: always in the account menu. */
+    placement?: TopAppBarActionPlacement;
+    /**
+     * The menu section the entry belongs to ("Language", "Theme"): its entries
+     * sit under that label, inline (never in a submenu, which overflows at
+     * 360 px). Entries without one come first.
+     */
+    group?: string;
+    /**
+     * The current choice of its group: a group of non-link entries where one
+     * sets `selected` is a radio group (`menuitemradio`, `aria-checked`); a
+     * link entry with `selected` is the current page (`aria-current="page"`).
+     */
+    selected?: boolean;
+    disabled?: boolean;
+};
+/** The screen's main action: a `Button` from 768 px, a `Fab` above the bottom chrome on a phone. */
+export type TopAppBarPrimaryAction = {
+    label: string;
+    /** Required: the phone's FAB is its icon. */
+    icon: ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+};
+/**
+ * @internal kept so the shell keeps its app-header* slots; removed with the slot rename in the next major
+ *
+ * The `data-slot` of the bar's parts, for a bar that must keep other names
+ * (the shell's `app-header*`). The bar's own root `data-slot` is overridden
+ * the usual way, as a prop. top-app-bar.css styles both names.
+ */
+export type TopAppBarSlotNames = Partial<Record<'title' | 'titleBlock' | 'subtitle' | 'headline' | 'collapsedTitle' | 'tabs', string>>;
+export type TopAppBarProps = {
+    /** @internal kept so the shell keeps its app-header* slots; removed with the slot rename in the next major */
+    slotNames?: TopAppBarSlotNames;
+    /** @internal the shell's leading title: drawn with the title in one box whose width does not come from its content (a size container), so the title can be hidden when squeezed. */
+    titleLead?: ReactNode;
+    /**
+     * The bar's height. `'small'` (the default): one row. `'medium-flexible'`
+     * and `'large-flexible'`: the `title` on a second row, 28 px and 40 px
+     * (36 px on a phone). `'search'`: the `search` field is the bar's centre.
+     * Without a `title`, a medium or large bar draws as `'small'`.
+     */
+    size?: TopAppBarSize;
+    /** `'center'` centres a `small` bar's title. Default `'start'`. */
+    align?: TopAppBarAlign;
+    /** The page's heading: the bar renders it as the one `<h1>`. */
+    title?: ReactNode;
+    /** An `id` for the `<h1>`, to name a region with `aria-labelledby`. */
+    titleId?: string;
+    /** A line under the title, in muted text: a `<p>` right after the `<h1>`, one line, truncated. */
+    subtitle?: ReactNode;
+    /** Beside the title: a badge, a status. */
+    titleAfter?: ReactNode;
+    /** At the start of the row: a menu or back button. */
+    leading?: ReactNode;
+    /**
+     * The row's actions, at its end. A `ReactNode` is drawn as given. An array
+     * of `TopAppBarAction` draws free ghost icon buttons (one on a phone, two
+     * from 768 px) and gathers the others, and the actions placed in
+     * `'account'`, in a menu opened by `trailing` (the avatar), or by a More
+     * button when there is no `trailing`.
+     */
+    actions?: ReactNode | TopAppBarAction[];
+    /**
+     * The very end of the row: an avatar. With an `actions` array of data it
+     * becomes the account menu's trigger (a `<button>`), so it must be
+     * non-interactive: no link, button or input inside (a warning in
+     * development).
+     */
+    trailing?: ReactNode;
+    /**
+     * The screen's main action: a `Button` from 768 px, a `Fab` above the
+     * bottom chrome on a phone. Both are in the markup and CSS shows one. After
+     * mount the phone's Fab is portalled to `document.body`, so a transformed
+     * ancestor (a sliding header, a backdrop blur) cannot break its
+     * `position: fixed`.
+     */
+    primaryAction?: TopAppBarPrimaryAction;
+    /** The field of a `'search'` bar. */
+    search?: ReactNode;
+    /** A row under the bar: a `Tabs` list. */
+    tabs?: ReactNode;
+    /** Marks the bar as one that collapses its second row on scroll (`data-collapse`). */
+    collapse?: boolean;
+    /** Marks the bar as one that hides on scroll down (`data-hide-on-scroll`). */
+    hideOnScroll?: boolean;
+    /** The link an action with an `href` renders: the nearest `LinkComponentProvider`'s, else `'a'`. */
+    linkComponent?: LinkComponent;
+    /** The element drawn: `'div'` (the default) or `'header'`. */
+    as?: 'div' | 'header';
+    /** @deprecated Use `size` and `align`: `'center'` is `small` + `align="center"`, `'medium'` is `'medium-flexible'`, `'large'` is `'large-flexible'`. */
+    variant?: 'small' | 'center' | 'medium' | 'large';
+    /** @deprecated Use `title`, which renders the bar's own `<h1>`. `headline` renders in a non-heading `<div>` (put your own heading element in it) with the bar's title styling. */
+    headline?: ReactNode;
+} & Omit<ComponentProps<'div'>, 'title'>;

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

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+import { TopAppBarAlign, TopAppBarProps, TopAppBarSize } from './top-app-bar.types.js';
+export type TopAppBarVariant = NonNullable<TopAppBarProps['variant']>;
+/** The size and align each deprecated `variant` stands for: the one table the bar and the shell read. */
+export declare const VARIANT_ALIASES: Record<TopAppBarVariant, [
+    TopAppBarSize,
+    TopAppBarAlign
+]>;
+/**
+ * The size and align a bar draws: the deprecated `variant` wins over the
+ * defaults only when `size` and `align` are not given.
+ */
+export declare function toSizeAlign(props: Pick<TopAppBarProps, 'size' | 'align' | 'variant'>): {
+    size: TopAppBarSize;
+    align: TopAppBarAlign;
+};
+/** The deprecated `variant` that draws a size and align (`'small'` for the sizes with none, a `search` bar included). */
+export declare function variantOf(size: TopAppBarSize, align: TopAppBarAlign): TopAppBarVariant;
+/** The old `data-variant` value of a bar, kept for styles written against it. */
+export declare function legacyVariant(size: TopAppBarSize, align: TopAppBarAlign): string | undefined;
+/**
+ * The bar's title: `title`, else the deprecated `headline` (which warns once
+ * and renders in a non-heading element).
+ */
+export declare function resolveTitle(title: ReactNode, headline: ReactNode): {
+    title: ReactNode;
+    legacy: boolean;
+};
+/** Whether a bar has a headline row: a medium or large size with a title. */
+export declare function hasHeadlineRow(size: TopAppBarSize | 'none', title: unknown): boolean;
+/** The bar's data attributes: the look, and the scroll behaviours it opts into. */
+export declare function barAttributes({ size, align, collapse, hideOnScroll, }: {
+    size: TopAppBarSize;
+    align: TopAppBarAlign;
+    collapse?: boolean;
+    hideOnScroll?: boolean;
+}): {
+    'data-variant': string | undefined;
+    'data-size': TopAppBarSize;
+    'data-align': TopAppBarAlign;
+    'data-collapse': string | undefined;
+    'data-hide-on-scroll': string | undefined;
+};

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

@@ -1,8 +1,8 @@
 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';
+import { ShellTopAppBar } from './shell-top-app-bar.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;
@@ -20,10 +20,10 @@ export declare function ActivityScroll({ on, region, children, }: {
     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.
+ * The app bar of {@link ActivityLayout}: a {@link TopAppBar} drawn as the
+ * page's `<header>`, in the size the route resolved. The page's title is its
+ * one `h1`; a medium or large size puts it on a second row (the small row then
+ * holds a faded copy of it), the others keep it in the row.
  */
 export declare function ActivityAppBar({ header, back, bar, headerTitle, hasBackdrop, ...props }: {
     header: ResolvedHeader;
@@ -31,5 +31,5 @@ export declare function ActivityAppBar({ header, back, bar, headerTitle, hasBack
     bar: BarProps;
     headerTitle?: ReactNode;
     hasBackdrop: boolean;
-} & Omit<ComponentProps<typeof AppHeader>, 'children' | 'variant' | 'headline'>): import("react").JSX.Element | null;
+} & Omit<ComponentProps<typeof ShellTopAppBar>, 'children' | 'size' | 'align' | 'headline' | 'title'>): import("react").JSX.Element | null;
 export {};

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

@@ -7,9 +7,12 @@ export declare const CHROME_FILL = "bg-(--nxgt-backdrop-fill-chrome)";
  * 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).
+ * The sticky app bar's classes. At rest it keeps the shell's fill
+ * (app-header.css, the page colour at 90%), tinted by top-app-bar.css once the
+ * page scrolls. Under a `backdrop` its fill is the chrome's translucent token
+ * (activity-backdrop.css), frosted: a utility class, so it wins over the bar's
+ * at-rest ground (a lower layer); once scrolled, app-header.css gives the fill
+ * back over the tint.
  */
 export declare const appBarClass: (hasBackdrop: boolean) => string;
 /** The sidebar: a little more opaque than the app bar, for its text's contrast. */

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

@@ -1,5 +1,5 @@
 import { ActivityLayoutProps } from './activity-layout.types.js';
-declare const COLUMN_KEYS: readonly ["context", "headerTitle", "titleAfter", "headerContext", "breadcrumb", "breadcrumbRoot", "headerActions", "avatar", "menuOpen", "onMenuOpenChange", "keepClear"];
+declare const COLUMN_KEYS: readonly ["context", "headerTitle", "titleAfter", "headerContext", "breadcrumb", "breadcrumbRoot", "headerActions", "headerPrimaryAction", "avatar", "menuOpen", "onMenuOpenChange", "keepClear"];
 type ColumnKey = (typeof COLUMN_KEYS)[number];
 export type ColumnOwnProps = Pick<ActivityLayoutProps, ColumnKey>;
 /**

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

@@ -1,6 +1,6 @@
 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' | 'header'> & {
+type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'titleAfter' | 'headerContext' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'headerPrimaryAction' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop' | 'keepClear' | 'header'> & {
     /** The element of the content region. */
     as: 'main' | 'div';
     contained: boolean;
@@ -21,5 +21,5 @@ type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name'
  * 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, headerTitle, titleAfter, headerContext, breadcrumb, breadcrumbRoot, headerActions, avatar, routeTransition, backdrop, keepClear, showMenu, topNav, floating, trackScroll, header, children, ...menu }: ColumnProps): import("react").JSX.Element;
+export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, headerTitle, titleAfter, headerContext, breadcrumb, breadcrumbRoot, headerActions, headerPrimaryAction, 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

@@ -31,8 +31,27 @@ export type ShellNavigationOptions = {
     /** 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';
+/**
+ * The height and kind of the shell header's bar. `'search'` is the search app
+ * bar: the `search` field is the bar's centre, and the title stays for
+ * assistive technology.
+ */
+export type ShellHeaderSize = 'small' | 'medium-flexible' | 'large-flexible' | 'search';
+/** Where the bar's title sits. */
+export type ShellHeaderAlign = 'start' | 'center';
+/**
+ * The shell header's look: a `ShellHeaderSize`, or `'none'` for no header.
+ * `'center'`, `'medium'` and `'large'` are deprecated aliases kept working:
+ * `'center'` is `'small'` with `align: 'center'`, `'medium'` is
+ * `'medium-flexible'` and `'large'` is `'large-flexible'`.
+ */
+export type ShellHeaderVariant = ShellHeaderSize | 'none'
+/** @deprecated Use `{ size: 'small', align: 'center' }`. */
+ | 'center'
+/** @deprecated Use `'medium-flexible'`. */
+ | 'medium'
+/** @deprecated Use `'large-flexible'`. */
+ | 'large';
 /**
  * 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
@@ -44,8 +63,17 @@ export type ShellBack = true | {
 };
 /** 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' */
+    /** The bar's size. @default 'small' */
+    size?: ShellHeaderSize;
+    /** Where the title sits. @default 'start' */
+    align?: ShellHeaderAlign;
+    /**
+     * `'none'` draws no header; the other values are the old spelling of `size`
+     * and `align`, mapped to them.
+     * @deprecated Use `size` and `align` (`'none'` stays valid here).
+     */
+    variant?: ShellHeaderVariant;
+    /** Whether a `medium-flexible` or `large-flexible` header collapses to the small one while scrolling. @default true for those two sizes */
     collapse?: boolean;
     /** Whether the header slides away while scrolling down. @default false */
     hideOnScroll?: boolean;

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

@@ -1,4 +1,5 @@
 import { ComponentProps, ReactNode } from 'react';
+import { TopAppBarAction, TopAppBarPrimaryAction } from '../app-bar/top-app-bar/top-app-bar.types.js';
 import { ActivityLayoutNavigationProps } from './activity-layout-navigation.types.js';
 import { AppBreadcrumbRoot } from './app-breadcrumb.js';
 import { RouteTransition } from './route-transition.js';
@@ -60,8 +61,17 @@ export type ActivityLayoutProps = {
     breadcrumb?: boolean;
     /** The breadcrumb's first crumb: a text link, or (`icon: true`) the home icon alone with its own target and name. */
     breadcrumbRoot?: AppBreadcrumbRoot;
-    /** Passed to the header, before the avatar. */
-    headerActions?: ReactNode;
+    /**
+     * Passed to the header, before the avatar. A node is drawn as given; an
+     * array of `TopAppBarAction` (data) draws free icon buttons, with the rest
+     * in the account menu opened by the `avatar`.
+     */
+    headerActions?: ReactNode | TopAppBarAction[];
+    /**
+     * The screen's main action in the app bar: a `Button` from 768 px, a `Fab`
+     * above the bottom chrome on a phone (`TopAppBar`'s `primaryAction`).
+     */
+    headerPrimaryAction?: TopAppBarPrimaryAction;
     /** Passed to the header. An image URL, or a whole node. */
     avatar?: ReactNode;
     /**

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

@@ -1,4 +1,5 @@
 import { PropsWithChildren, ReactNode } from 'react';
+import { TopAppBarAction } from '../app-bar/top-app-bar/top-app-bar.types.js';
 import { AppSearchBarProps } from '../app-search/app-search.types.js';
 import { ShellBack } from './activity-layout-navigation.types.js';
 import { AppLogo, AppShellLinkComponent, MenuItem } from './types.js';
@@ -11,7 +12,7 @@ export type AppHeaderProps = {
     /** The classes hiding the top navigation (`navigation="top"`) where it does not show, drawn right after the menu button with the brand; undefined: none. */
     topNav?: string;
     /** Rendered before the avatar — notifications, help, a theme toggle. */
-    actions?: ReactNode;
+    actions?: ReactNode | TopAppBarAction[];
     /** An image URL, or a whole node when the app renders its own. */
     avatar?: ReactNode;
     /** The menu sheet's sidebar header; see `AppSidebar`'s `brand`. */
@@ -63,7 +64,12 @@ export type AppHeaderProps = {
     headline?: ReactNode;
 } & PropsWithChildren;
 /**
- * The top bar. On mobile it also *is* the navigation: the sidebar is hidden by
+ * The top bar.
+ *
+ * @deprecated Use `TopAppBar`, which `ActivityLayout` draws its own bar with.
+ * `AppHeader` stays as a wrapper over it, with the props it always had.
+ *
+ * On mobile it also *is* the navigation: the sidebar is hidden by
  * the layout and reappears here inside a `Sheet`, which is why this component
  * takes `items` at all.
  *
@@ -75,4 +81,4 @@ export type AppHeaderProps = {
  * {@link ActivityLayout}: the menu sheet reads the location to close when it
  * changes, and `useLocation` throws outside a router.
  */
-export declare function AppHeader({ className, children, variant, collapse, hideOnScroll, headline, tabs, ...row }: AppHeaderProps): import("react").JSX.Element;
+export declare function AppHeader({ variant, headline, children, ...props }: AppHeaderProps): import("react").JSX.Element;

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

@@ -0,0 +1,14 @@
+import { ShellHeaderAlign, ShellHeaderOptions, ShellHeaderSize, ShellHeaderVariant } from './activity-layout-navigation.types.js';
+/** A header's size and alignment, new spelling only. */
+export type HeaderLook = {
+    size?: ShellHeaderSize | 'none';
+    align?: ShellHeaderAlign;
+};
+/** The new spelling of each old variant. */
+export declare function variantLook(variant: ShellHeaderVariant): HeaderLook;
+/**
+ * The header an input spells, with the old `variant` values mapped to `size`
+ * and `align` (a dev-only warning names the new spelling). `size` and `align`
+ * win over `variant`. Only the options the input sets are returned.
+ */
+export declare function normalizeHeader(header?: ShellHeaderVariant | ShellHeaderOptions): Omit<ShellHeaderOptions, 'variant' | 'size' | 'align'> & HeaderLook;

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

@@ -1,43 +1,16 @@
 import { ReactNode } from 'react';
 /**
- * The header's leading title, truncated with an ellipsis when long. Only
- * then does it carry a `title` with the full text (#629): the accessible
- * name stays the content itself. When the actions leave the bar's title area
- * under 4.5rem (an ellipsis and a glyph do not fit), it is visually hidden
- * (`sr-only`) and stays in the accessibility tree (#1693): a container query
- * on the bar, so the server markup is unchanged.
+ * The header's leading title (the active organisation), truncated with an
+ * ellipsis when long. Only then does it carry a `title` with the full text
+ * (#629): the accessible name stays the content itself. It is as wide as its
+ * text, up to 35% of the titles' box (45% from `sm`) when the page's title
+ * shares it (alone, it keeps the whole box and goes under 4.5rem). When that box is under 8rem (the share would be an ellipsis and
+ * a sliver) it is visually hidden (`sr-only`) and stays in the accessibility
+ * tree (#1693): a container query on the box the bar draws around the titles
+ * (top-app-bar-row.tsx), whose width does not come from its content.
  */
-export declare function HeaderTitle({ children, shrinks, center, }: {
+export declare function HeaderTitle({ children, shrinks, }: {
     children?: ReactNode;
-    /** Centre it, for the `'center'` header. */
-    center?: boolean;
     /** The page's title shares the bar: this one gives it room. */
     shrinks?: boolean;
 }): import("react").JSX.Element | null;
-/**
- * The page's title in the small bar of a medium or large header, a copy of the
- * headline's text for the eye: hidden from the accessibility tree (the headline
- * is the page's `h1`) and faded in by app-header.css as the headline collapses.
- */
-export declare function CollapsedTitle({ children, separated, }: {
-    children: ReactNode;
-    /** A leading title precedes it: a thin rule between them. */
-    separated?: boolean;
-}): import("react").JSX.Element;
-/**
- * The app bar's titles: the leading `headerTitle`, then the page's title (a
- * route's `handle.title`, the page's `h1`) after a thin rule when both are set.
- */
-export declare function AppBarTitles({ headerTitle, pageTitle, pageTitleAfter, headerContext, titleId, center, collapsedTitle, }: {
-    headerTitle?: ReactNode;
-    pageTitle?: ReactNode;
-    /** The slot right after the page's title, outside its `h1`. */
-    pageTitleAfter?: ReactNode;
-    /** The small muted context line after the title, from `md` up. */
-    headerContext?: ReactNode;
-    titleId?: string;
-    /** The `'center'` header: the titles are centred. */
-    center?: boolean;
-    /** The page's title for a medium or large header, whose headline row carries the `h1`: the bar shows this copy once collapsed. */
-    collapsedTitle?: ReactNode;
-}): import("react").JSX.Element;

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

@@ -2,10 +2,12 @@ import { UIMatch } from 'react-router';
 import { ShellBack, ShellHeaderOptions, ShellHeaderVariant } from './activity-layout-navigation.types.js';
 /** What `header` and a route's `handle.header` take. */
 export type ShellHeaderInput = ShellHeaderVariant | ShellHeaderOptions;
-/** The px a `medium` or `large` header gives back while it collapses (the headline row), in rem: 16px each. */
+/** The headline row a header gives back while it collapses, by size, in rem (16px each): the height used before the real one is measured (the server, first paint). */
 export declare const HEADLINE_REM: {
-    readonly medium: 5;
-    readonly large: 8;
+    readonly small: 0;
+    readonly 'medium-flexible': 3;
+    readonly 'large-flexible': 6.5;
+    readonly search: 0;
 };
 /** Px of scroll past which a header that hides on scroll goes away. */
 export declare const HIDE_AFTER = 64;
@@ -33,5 +35,13 @@ export declare function mergeHeader(layout?: ShellHeaderInput, route?: ShellHead
  * middle instead of following the scroll.
  */
 export declare function collapseProgress(offset: number, range: number, reducedMotion?: boolean): number;
+/** Whether the page has scrolled at all: the bar leaves the ground for its tint and hairline. */
+export declare function isHeaderScrolled(offset: number): boolean;
+/**
+ * The px of scroll a collapse takes: the measured headline row when there is
+ * one, else `fallback` (the server, before mount, no `ResizeObserver`). 0
+ * (a bar that does not collapse) stays 0.
+ */
+export declare function collapseRange(fallback: number, measured?: number): number;
 /** Whether a header that hides on scroll is away: scrolling down, past `after` px. */
 export declare function isHeaderHidden(direction: 'up' | 'down' | 'none', offset: number, after?: number): boolean;

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

@@ -10,5 +10,5 @@ export { DEFAULT_NAVIGATION, navigationClasses, type ResolvedHeader, type Resolv
 export { usePageTitleFocus } from './page-title-focus.js';
 export type { AppShellHandle, PageTitle } from './page-title-scope.js';
 export { ROUTE_TRANSITION_CLASS, type RouteTransition, } from './route-transition.js';
-export { ShellScrollContext, type ShellScrollDirection, type ShellScrollOptions, ShellScrollProvider, type ShellScrollState, useScrollTracker, useShellScroll, } from './shell-scroll.js';
+export { ShellScrollContext, type ShellScrollDirection, type ShellScrollOptions, ShellScrollProvider, type ShellScrollPublisher, type ShellScrollState, useScrollTracker, useShellScroll, } from './shell-scroll.js';
 export * from './types.js';