@nxgt/material 3.79.0 → 3.80.0

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

@@ -1,4 +1,6 @@
 import { PropsWithChildren, ReactNode } from 'react';
+import { AppSearchBarProps } from '../app-search/app-search.types.js';
+import { ShellBack } from './activity-layout-navigation.types.js';
 import { AppLogo, AppShellLinkComponent, MenuItem } from './types.js';
 export type AppHeaderProps = {
     className?: string;
@@ -6,6 +8,8 @@ export type AppHeaderProps = {
     items: MenuItem[];
     /** The link of each menu entry; see {@link AppShellLinkComponent}. */
     linkComponent?: AppShellLinkComponent;
+    /** 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;
     /** An image URL, or a whole node when the app renders its own. */
@@ -29,6 +33,34 @@ export type AppHeaderProps = {
     menuOpen?: boolean;
     /** Asked for every change of the menu sheet: the button, Escape, a link, a new location. */
     onMenuOpenChange?: (open: boolean) => void;
+    /**
+     * The bar's look. `'small'` (the default): one row. `'center'`: the title
+     * centred. `'medium'` and `'large'`: with a `headline`, a second row under
+     * the first, in display type, collapsing into the first as the shell scrolls;
+     * without one they draw as `'small'`.
+     */
+    variant?: 'small' | 'center' | 'medium' | 'large';
+    /** Whether a `medium` or `large` bar collapses while the shell scrolls. @default true */
+    collapse?: boolean;
+    /** Slides the bar away while the shell scrolls down, back on the way up: `inert` while away. @default false */
+    hideOnScroll?: boolean;
+    /** A search after the titles: a pill from 768px, a button for the full-screen view on a phone. Unset: none. */
+    search?: AppSearchBarProps;
+    /**
+     * A tab row under the bar (a `TabsNav`), stuck to it: it stays under the bar
+     * while a `medium` or `large` one collapses, and stays pinned at the top of
+     * the window when `hideOnScroll` slides the bar away. Unset: none.
+     */
+    tabs?: ReactNode;
+    /**
+     * A back arrow at the start of the bar: `{ to, label? }` links to `to`, `true`
+     * goes back in the history (or up one level when this is the first page of
+     * the visit). It comes first, before the menu button and the title; the
+     * phone's menu button follows it. Unset: none.
+     */
+    back?: ShellBack;
+    /** The page's title for a `medium` or `large` bar: its second row, which should carry the page's `h1`. */
+    headline?: ReactNode;
 } & PropsWithChildren;
 /**
  * The top bar. On mobile it also *is* the navigation: the sidebar is hidden by
@@ -43,4 +75,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({ items, linkComponent, className, children, actions, avatar, brand, logo, name, context, menuOpen, onMenuOpenChange, showMenuIcon, }: AppHeaderProps): import("react").JSX.Element;
+export declare function AppHeader({ className, children, variant, collapse, hideOnScroll, headline, tabs, ...row }: AppHeaderProps): import("react").JSX.Element;

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

@@ -42,3 +42,11 @@ export declare function isMenuItemActive(pathname: string, url: string): boolean
  * urls are the same url — so first-longest is deterministic.
  */
 export declare function findActiveMenuItem(pathname: string, items: MenuItem[]): MenuItem | undefined;
+/** Every entry and, after each, its children: the list the location is matched against. */
+export declare function flattenItems(items: MenuItem[]): MenuItem[];
+/**
+ * The top-level entry the location belongs to: the one whose own url or whose
+ * descendant's url is the most specific match. A child living outside its
+ * parent's url (`/archive` under `/projects`) still lights the parent.
+ */
+export declare function findActiveSection(pathname: string, items: MenuItem[]): MenuItem | undefined;

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

@@ -0,0 +1,13 @@
+import { AppShellLinkComponent, MenuItem } from './types.js';
+/**
+ * The sidebar's entries: a link per item, an icon button for `display: 'icon'`.
+ * Expanded (the sidebar open, the phone's menu sheet), an entry's `children`
+ * are nested under it, indented.
+ */
+export declare function AppSidebarEntries({ items, activeUrl, linkComponent, expanded, }: {
+    items: MenuItem[];
+    /** The `url` of the one current entry, a child included. */
+    activeUrl?: string;
+    linkComponent: AppShellLinkComponent;
+    expanded?: boolean;
+}): import("react").JSX.Element[];

package/dist/lib/components/ui/layout/app-shell/app-sidebar-label-item.d.ts

@@ -4,8 +4,10 @@ import { AppShellLinkComponent, MenuItem } from './types.js';
  * with its badge. The twin of {@link AppSidebarIconItem}, which draws an
  * entry with `display: 'icon'`.
  */
-export declare function AppSidebarLabelItem({ item, active, linkComponent: ownLink, }: {
+export declare function AppSidebarLabelItem({ item, active, linkComponent: ownLink, nested, }: {
     item: MenuItem;
     active: boolean;
+    /** A child of another entry: indented under it. */
+    nested?: boolean;
     linkComponent?: AppShellLinkComponent;
 }): import("react").JSX.Element;

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

@@ -0,0 +1,13 @@
+/**
+ * The room a bottom navigation bar and a docked media bar take at the bottom
+ * of the screen, as a CSS length: `--nxgt-bottom-chrome` when set, else the
+ * two added (`--nxgt-nav-bar` and `--nxgt-media-dock`, 0 when unset). The
+ * bar's room already holds the bottom safe-area inset, and so does a dock
+ * alone: the inset is cleared once, never added on top.
+ */
+export declare const BOTTOM_CHROME = "var(--nxgt-bottom-chrome, calc(var(--nxgt-nav-bar, 0px) + var(--nxgt-media-dock, 0px)))";
+/**
+ * What a floating element clears at the bottom: the bottom safe-area inset or
+ * the chrome, whichever is taller (the chrome holds the inset when it shows).
+ */
+export declare const BOTTOM_CLEARANCE = "max(env(safe-area-inset-bottom, 0px), var(--nxgt-bottom-chrome, calc(var(--nxgt-nav-bar, 0px) + var(--nxgt-media-dock, 0px))))";

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

@@ -7,16 +7,28 @@ import { ReactNode } from 'react';
  * (`sr-only`) and stays in the accessibility tree (#1693): a container query
  * on the bar, so the server markup is unchanged.
  */
-export declare function HeaderTitle({ children, shrinks, }: {
+export declare function HeaderTitle({ children, shrinks, center, }: {
     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, }: {
+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`. */
@@ -24,4 +36,8 @@ export declare function AppBarTitles({ headerTitle, pageTitle, pageTitleAfter, h
     /** 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

@@ -0,0 +1,37 @@
+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. */
+export declare const HEADLINE_REM: {
+    readonly medium: 5;
+    readonly large: 8;
+};
+/** Px of scroll past which a header that hides on scroll goes away. */
+export declare const HIDE_AFTER = 64;
+/**
+ * The `handle.back` of the deepest matched route that declares one, or
+ * `undefined`. Read from the matches, like the header, so the server draws
+ * the same bar.
+ */
+export declare function resolveRouteBack(matches: UIMatch[]): ShellBack | undefined;
+/**
+ * The `handle.header` of the deepest matched route that declares one, or
+ * `undefined`: read from the matches, which the router has before it renders
+ * anything, so the server draws the same header.
+ */
+export declare function resolveRouteHeader(matches: UIMatch[]): ShellHeaderInput | undefined;
+/**
+ * The header a screen gets: the layout's `header` with the route's
+ * `handle.header` on top, option by option. A route that only names a variant
+ * keeps the layout's `hideOnScroll`.
+ */
+export declare function mergeHeader(layout?: ShellHeaderInput, route?: ShellHeaderInput): import('./navigation.utils.js').ResolvedHeader;
+/**
+ * How far a collapsing header has gone, 0 (expanded) to 1 (collapsed), after
+ * `offset` px of scroll over `range` px. Under reduced motion it snaps at the
+ * middle instead of following the scroll.
+ */
+export declare function collapseProgress(offset: number, range: number, reducedMotion?: boolean): 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

@@ -1,11 +1,14 @@
 export * from './activity-content.js';
 export type * from './activity-content-aside.types.js';
 export * from './activity-layout.js';
+export type * from './activity-layout-navigation.types.js';
 export * from './app-breadcrumb.js';
 export * from './app-header.js';
 export * from './app-shell.utils.js';
 export * from './app-sidebar.js';
+export { DEFAULT_NAVIGATION, navigationClasses, type ResolvedHeader, type ResolvedNavigation, resolveHeader, resolveNavigation, } from './navigation.utils.js';
 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 * from './types.js';

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

@@ -0,0 +1,38 @@
+import { ShellNavigation } from './activity-layout-navigation.types.js';
+import { ResolvedNavigation } from './navigation.utils.js';
+/**
+ * Whether the shell draws each preset; one still to come is `false` and draws
+ * what its size has by default. Every `ShellNavigation` name is drawn today.
+ */
+export declare const DRAWN: Record<ShellNavigation, boolean>;
+export type ShellParts = {
+    /** Present when a bar shows at some size: the classes that hide it elsewhere, and its `--nxgt-nav-bar` for the first paint. */
+    bar?: {
+        hide: string;
+        vars: string;
+    };
+    /** The classes hiding the rail where it does not show; undefined: no rail. */
+    rail?: string;
+    /** The classes hiding the wide navigation rail where it does not show; undefined: no such rail. */
+    wide?: string;
+    /** The classes hiding the permanent drawer where it does not show; undefined: no such drawer. */
+    drawer?: string;
+    /** The classes hiding the collapsible sidebar where it does not show; undefined: no sidebar. */
+    sidebar?: string;
+    /** The classes hiding the top navigation (in the app header) where it does not show; undefined: no top navigation. */
+    top?: string;
+    /** The classes hiding the two-level navigation (rail and section panel) where it does not show; undefined: none. */
+    twoLevel?: string;
+    /** Present when the floating navigation toolbar shows at some size: the classes that hide it elsewhere, its first-paint `--nxgt-nav-bar`, and whether it slides away on scroll. */
+    floating?: {
+        hide: string;
+        vars: string;
+        hideOnScroll: boolean;
+    };
+    /** The key the wide rail keeps its state under. */
+    persistKey?: string;
+    /** Whether the phone has the app bar's menu button (the modal drawer). */
+    menu: boolean;
+};
+/** What the shell renders for a resolved navigation, each part switched by CSS classes. */
+export declare function shellParts(navigation: ResolvedNavigation): ShellParts;

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

@@ -0,0 +1,36 @@
+import { AppSearchBarProps } from '../app-search/app-search.types.js';
+import { ShellHeaderOptions, ShellHeaderVariant, ShellNavigation, ShellNavigationOptions } from './activity-layout-navigation.types.js';
+/** What the shell draws today, and what an unset `navigation` resolves to. */
+export declare const DEFAULT_NAVIGATION: {
+    readonly phone: "modal-drawer";
+    readonly tablet: "rail";
+    readonly desktop: "rail";
+};
+export type ResolvedNavigation = {
+    phone: ShellNavigation;
+    tablet: ShellNavigation;
+    desktop: ShellNavigation;
+    hideOnScroll: boolean;
+    persistKey?: string;
+};
+export type ResolvedHeader = {
+    variant: ShellHeaderVariant;
+    collapse: boolean;
+    hideOnScroll: boolean;
+    tabs: ShellHeaderOptions['tabs'];
+    /** The search's props, `{}` for `search: true`; undefined: none. */
+    search: AppSearchBarProps | undefined;
+};
+/** Whether `preset` is drawn on a phone at all: no rail, no top bar and no two levels (the sidebar and the drawer only when named for it). */
+export declare function drawnOnPhone(preset: ShellNavigation): boolean;
+/** A preset name alone applies to every window size it is drawn at: a phone keeps its menu sheet for the rails, the sidebar, the drawer, the top bar and the two-level navigation, and the bottom bar is the phone's alone (`{ tablet: 'bar' }` asks for it from 768px). */
+export declare function resolveNavigation(navigation?: ShellNavigation | ShellNavigationOptions): ResolvedNavigation;
+export declare function resolveHeader(header?: ShellHeaderVariant | ShellHeaderOptions): ResolvedHeader;
+/** The classes hiding a part at the sizes its 3-character key (phone, tablet, desktop; 1 = shown) leaves out. */
+export declare function hideClasses(key: string): string;
+/**
+ * For each preset the navigation uses, the classes that show it only at the
+ * window sizes it is configured for (`'rail'` on the tablet and the desktop:
+ * `max-md:hidden`). Presets not in use have no entry.
+ */
+export declare function navigationClasses(navigation: ResolvedNavigation): Partial<Record<ShellNavigation, string>>;

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

@@ -1,5 +1,7 @@
 import { ReactNode } from 'react';
 import { UIMatch } from 'react-router';
+import { ShellBack } from './activity-layout-navigation.types.js';
+import { ShellHeaderInput } from './header.utils.js';
 /**
  * A route's `handle.title`: the page's title in the app bar. A node, or a
  * function of the matched route (its `params`, its loader `data`) returning
@@ -21,6 +23,18 @@ export type AppShellHandle<Data = unknown> = {
      * shows no page title.
      */
     titleAfter?: PageTitle<Data>;
+    /**
+     * The app bar for this route: a variant (`'small'`, `'center'`, `'medium'`,
+     * `'large'`, `'none'`) or the variant with its options, on top of
+     * `ActivityLayout`'s `header`. The deepest route declaring one wins.
+     */
+    header?: ShellHeaderInput;
+    /**
+     * A back arrow at the start of this route's app bar: `{ to, label? }` or
+     * `true` (history back, up one level when the visit started here). On a
+     * phone the menu button follows it. The deepest route declaring one wins.
+     */
+    back?: ShellBack;
 };
 /**
  * The title of the deepest matched route that declares a `handle.title`, or

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

@@ -1,4 +1,10 @@
 import { ReactNode } from 'react';
+/** The type step and the fit of each size. */
+declare const SIZES: {
+    readonly bar: readonly ["title-medium", "min-w-0 max-md:line-clamp-2 max-md:break-words md:truncate"];
+    readonly headline: readonly ["headline-lg", "min-w-0 truncate"];
+    readonly display: readonly ["display-md", "min-w-0 line-clamp-2 break-words"];
+};
 /**
  * The page's one `h1`, in the app bar: from `md` up truncated with an
  * ellipsis when long, on a phone wrapped to two lines first (a record's number
@@ -6,11 +12,16 @@ import { ReactNode } from 'react';
  * with the full text (as the header's leading title does, #629); the accessible name is the content itself.
  * The display face is `--font-display`, the body face without it.
  */
-export declare function PageHeading({ children, id, after, context, }: {
+export declare function PageHeading({ children, id, after, context, size, center, }: {
     children?: ReactNode;
     id?: string;
     /** The slot right after the title, outside the `h1`: it never truncates, the title does. */
     after?: ReactNode;
     /** The small muted context line (the tenant), last in the row, from `md` up. */
     context?: ReactNode;
+    /** `'bar'`: the title in the app bar. `'headline'` and `'display'`: the second row of a medium and a large header, which wraps (display up to two lines). */
+    size?: keyof typeof SIZES;
+    /** Centre it, for the `'center'` header. */
+    center?: boolean;
 }): import("react").JSX.Element | null;
+export {};

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

@@ -0,0 +1,32 @@
+import { ReactNode, RefObject } from 'react';
+export type ShellScrollDirection = 'up' | 'down' | 'none';
+export type ShellScrollState = {
+    /** Where the scrolling went last, once it moved by more than the threshold; `'none'` at the top. */
+    direction: ShellScrollDirection;
+    /** The scroll offset in px (0 at the top). */
+    offset: number;
+    /** Whether the user asked for reduced motion: skip the slide and snap. */
+    reducedMotion: boolean;
+};
+/** The shell's scroll state; idle outside a {@link ShellScrollProvider}. */
+export declare const ShellScrollContext: import('react').Context<ShellScrollState>;
+/** The shell's scroll direction and offset, for a header or bar that hides on scroll. */
+export declare function useShellScroll(): ShellScrollState;
+export type ShellScrollOptions = {
+    /** The scrolling box; `null` (default) is the window. */
+    container?: RefObject<HTMLElement | null> | null;
+    /** Px of movement before the direction flips. @default 8 */
+    threshold?: number;
+    /** `false`: track nothing (no listener, no frame) and stay idle. @default true */
+    enabled?: boolean;
+};
+/**
+ * Tracks one scroller: reads once per animation frame, flips the direction
+ * only after `threshold` px of movement the other way (hysteresis). Idle on
+ * the server and until mounted.
+ */
+export declare function useScrollTracker({ container, threshold, enabled, }?: ShellScrollOptions): ShellScrollState;
+/** Provides {@link useShellScroll} for one scroller (the window, or `container`). */
+export declare function ShellScrollProvider({ children, ...options }: ShellScrollOptions & {
+    children: ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+/**
+ * Under the app bar: the bar's gutter, its whole height (`--nxgt-header-total`:
+ * the row, a headline row and the tabs, measured by `useHeaderHeight`, or
+ * worked out by app-header.css before it runs) and the gap below it. In a
+ * `scroll="container"` shell the region scrolls below the bar, so the panel
+ * sticks to the region's top and leaves room for the breadcrumb.
+ */
+export declare const STICKY_OFFSET: string;

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

@@ -49,6 +49,20 @@ export type MenuItem = {
      * badge reads nothing unless you give one.
      */
     badgeLabel?: string;
+    /**
+     * Sub-entries. `navigation="top"` opens them in a dropdown under the entry
+     * (which then is a button, not a link) and the expanded sidebar and the
+     * phone's menu sheet nest them under it; `navigation="two-level"` lists them
+     * in the panel beside the rail (one level); the collapsed rail and the other
+     * presets list the top level only.
+     */
+    children?: MenuItem[];
+    /** The section this entry belongs to, already translated: the drawer draws one section per group. */
+    group?: string;
+    /** Whether a bottom navigation bar shows this entry (the others go under "More"): the bar and the floating toolbar. */
+    bar?: boolean;
+    /** Orders the entries a bar keeps when there is room for fewer: higher stays. */
+    priority?: number;
 };
 /** An image logo: its URL, and the text it stands for when no `name` is given. */
 export type AppLogoImage = {

package/dist/lib/components/ui/layout/app-shell/use-focus-while-hidden.d.ts

@@ -0,0 +1,9 @@
+import { RefObject } from 'react';
+/**
+ * Keeps the focus out of a bar that slides away (it turns `inert`): focus
+ * inside it moves to the content region (or is released when the page has
+ * none), and returns to where it was once the bar is back, unless the user
+ * went elsewhere meanwhile. `keep` names the focused elements that stay on
+ * screen and so are left alone (the header's tabs).
+ */
+export declare function useFocusWhileHidden(ref: RefObject<HTMLElement | null>, hidden: boolean, keep?: (active: Element) => boolean): void;

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

@@ -0,0 +1,12 @@
+import { RefObject } from 'react';
+/** The CSS variable on the layout root: the bar's whole height, tabs and any extra row included. */
+export declare const HEADER_TOTAL_VAR = "--nxgt-header-total";
+/**
+ * Publishes the bar's real height (the row, a headline row, the tabs) as
+ * `--nxgt-header-total` on the closest `ActivityLayout` root, so the sticky
+ * panels (`STICKY_OFFSET`) stick below all of it. Measured with a
+ * `ResizeObserver`, through the CSSOM (no `style` attribute). On the server,
+ * before mount, and without a `ResizeObserver`, app-header.css computes it from
+ * the bar's variant and tabs. It writes only on change, at most once per frame, and not while a collapsing bar is between its two states. Outside an `ActivityLayout` it does nothing.
+ */
+export declare function useHeaderHeight(ref: RefObject<HTMLElement | null>): void;

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

@@ -0,0 +1,19 @@
+import { RefObject } from 'react';
+/** The CSS variable app-header.css reads: 0 expanded, 1 collapsed. */
+export declare const PROGRESS_VAR = "--nxgt-header-progress";
+/**
+ * Drives an app bar from the shell's scroll ({@link useShellScroll}, the
+ * window or the content region): how far its headline has collapsed, set as a
+ * CSS variable on the element (never an inline style string), and whether it
+ * has slid away. Idle (expanded, shown) on the server, outside a provider and
+ * before mount. Focus inside a bar that goes away moves out and comes back ({@link useFocusWhileHidden}).
+ */
+export declare function useHeaderScroll(ref: RefObject<HTMLElement | null>, { range, hideOnScroll, }: {
+    /** Px of scroll the collapse takes; 0: the bar does not collapse. */
+    range: number;
+    hideOnScroll: boolean;
+}): {
+    progress: number;
+    hidden: boolean;
+    collapsed: boolean;
+};

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

@@ -0,0 +1,20 @@
+import { ShellBack } from './activity-layout-navigation.types.js';
+import { ShellHeaderInput } from './header.utils.js';
+/**
+ * The header of the matched route: `ActivityLayout`'s `header` with the
+ * deepest `handle.header` on top. Read from the matches, so the server and
+ * the browser agree.
+ */
+export declare function useShellHeader(header?: ShellHeaderInput): import('./navigation.utils.js').ResolvedHeader;
+/** The back arrow of the matched route (`handle.back`), or `undefined`. */
+export declare function useShellBack(): ShellBack | undefined;
+/**
+ * The attributes `ActivityLayout` puts on its root for app-header.css, which
+ * works the bar's height out from them before any script runs: `data-header`
+ * (`medium` or `large`, only with a page title to put in the headline row) and
+ * `data-header-tabs`.
+ */
+export declare function useHeaderRootAttributes(header?: ShellHeaderInput): {
+    'data-header': import('./activity-layout-navigation.types.js').ShellHeaderVariant | undefined;
+    'data-header-tabs': string | undefined;
+};

package/dist/lib/components/ui/layout/auth-card/auth-card-split.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+/** The page's safe-area padding, as classes (no style attribute). */
+export declare const SAFE_PADDING = "pt-[max(1rem,env(safe-area-inset-top))] pr-[max(1rem,env(safe-area-inset-right))] pb-[max(1rem,env(safe-area-inset-bottom))] pl-[max(1rem,env(safe-area-inset-left))]";
+/**
+ * The two columns of `layout="split"`: the `visual` side from 768px (hidden
+ * on a phone, which keeps the form only under its compact brand row) and the
+ * form side, opaque so text and controls never sit on the backdrop. Placed by
+ * CSS breakpoint classes only, so the server and the client render the same
+ * markup.
+ */
+export declare function AuthCardSplit({ visual, children, }: {
+    visual?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/auth-card/auth-card.d.ts

@@ -40,6 +40,18 @@ export type AuthCardProps = Omit<ComponentProps<'main'>, 'title'> & {
      * or card).
      */
     keepClear?: boolean | 'gaps';
+    /**
+     * `'card'` (the default) is a centred card; `'split'` is two columns from
+     * 768px, the `visual` side and the form side, and the form alone (under
+     * the brand row) on a phone.
+     */
+    layout?: 'card' | 'split';
+    /**
+     * With `layout="split"`: the side beside the form, from 768px (a `Background`
+     * preset with `className="absolute inset-0"`, a picture, a tagline). It is
+     * hidden on a phone; mark a purely decorative one `aria-hidden`.
+     */
+    visual?: ReactNode;
     /** The form. */
     children: ReactNode;
 };
@@ -48,4 +60,4 @@ export type AuthCardProps = Omit<ComponentProps<'main'>, 'title'> & {
  * `main`, a centred card whose title is the page's `h1`, a row above it for
  * the brand and a toolbar, padded clear of a phone's notch and home bar.
  */
-export declare function AuthCard({ title, description, notice, noticeTone, focusTitle, brand, toolbar, banner, footer, backdrop, keepClear, className, children, ...props }: AuthCardProps): import("react").JSX.Element;
+export declare function AuthCard({ title, description, notice, noticeTone, focusTitle, brand, toolbar, banner, footer, backdrop, keepClear, layout, visual, className, children, ...props }: AuthCardProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/dashboard-grid/dashboard-grid-context.d.ts

@@ -0,0 +1,21 @@
+import { DashboardColumns, ReorderDirection } from './dashboard-grid.utils.js';
+/** Which control of a tile takes the focus back after the tile has moved. */
+export type DashboardFocusTarget = 'handle' | 'earlier' | 'later';
+export type DashboardGridContextValue = {
+    editing: boolean;
+    order: string[];
+    columns: Required<DashboardColumns>;
+    grabbedId: string | null;
+    /** The id of the element describing the keys, for the handles. */
+    hintId: string;
+    /** Space, arrows, Escape on a handle; returns true when the key was used. */
+    onHandleKey: (id: string, key: string, rtl: boolean) => boolean;
+    onHandleBlur: (id: string) => void;
+    /** The earlier / later buttons of the narrow layout. */
+    onMove: (id: string, direction: ReorderDirection, focus: DashboardFocusTarget) => void;
+    /** The control to focus once, after the tile moved. */
+    takeFocus: (id: string) => DashboardFocusTarget | null;
+};
+export declare const DashboardGridProvider: import('react').Provider<DashboardGridContextValue | null>;
+/** The grid a tile sits in, or `null` for a tile outside any grid. */
+export declare const useDashboardGridContext: () => DashboardGridContextValue | null;

package/dist/lib/components/ui/layout/dashboard-grid/dashboard-grid.d.ts

@@ -0,0 +1,9 @@
+import { DashboardGridProps } from './dashboard-grid.types.js';
+/**
+ * DashboardGrid - tiles in a responsive grid that the user can rearrange.
+ * An "Edit layout" button turns on edit mode: each tile gets a handle to drag
+ * with a pointer, or to pick up with Space, move with the arrows and drop
+ * with Space (Escape cancels); below 768px the tiles also get earlier / later
+ * buttons. The order is the app's: pass `order` and `onOrderChange`.
+ */
+export declare function DashboardGrid(props: DashboardGridProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/dashboard-grid/dashboard-grid.state.d.ts

@@ -0,0 +1,30 @@
+export type DashboardNoteKind = 'grabbed' | 'moved' | 'dropped' | 'cancelled';
+export type DashboardState = {
+    /** The tile picked up with the keyboard, and the order to put back on Escape. */
+    grabbed: {
+        id: string;
+        origin: string[];
+    } | null;
+    /** The last thing to say to a screen reader; `seq` repeats an identical message. */
+    note: {
+        kind: DashboardNoteKind;
+        id: string;
+        /** The order the note is about, so a lagging controlled `order` cannot misreport the position. */
+        order: string[];
+        seq: number;
+    } | null;
+};
+export type DashboardAction = {
+    type: 'grab';
+    id: string;
+    origin: string[];
+} | {
+    type: 'release';
+} | {
+    type: 'note';
+    kind: DashboardNoteKind;
+    id: string;
+    order: string[];
+};
+export declare const INITIAL_STATE: DashboardState;
+export declare function dashboardReducer(state: DashboardState, action: DashboardAction): DashboardState;

package/dist/lib/components/ui/layout/dashboard-grid/dashboard-grid.tiles.d.ts

@@ -0,0 +1,8 @@
+import { ReactElement } from 'react';
+import { DashboardGridProps } from './dashboard-grid.types.js';
+/** The tiles among the children by id, in the order they were written, with the name each answers to. */
+export declare function readTiles(children: DashboardGridProps['children']): {
+    elements: Map<string, ReactElement<unknown, string | import('react').JSXElementConstructor<any>>>;
+    labels: Record<string, string>;
+    ids: string[];
+};

package/dist/lib/components/ui/layout/dashboard-grid/dashboard-grid.types.d.ts

@@ -0,0 +1,50 @@
+import { ComponentProps, ReactNode } from 'react';
+import { ResponsiveGridGap } from '../responsive-grid/responsive-grid.utils.js';
+import { GridRowSpan, GridSpan, ResponsiveValue } from '../responsive-grid/responsive-grid-spans.js';
+import { DashboardColumns } from './dashboard-grid.utils.js';
+export type DashboardGridProps = Omit<ComponentProps<'div'>, 'children'> & {
+    /** `DashboardTile`s, written directly here (not inside a fragment or a wrapper): each one's `id` places it in the order. */
+    children: ReactNode;
+    /**
+     * The tiles' ids in display order (controlled). A tile `order` does not
+     * list goes after the listed ones, in the order it is written; an id with
+     * no tile is ignored. The app stores it (a user's saved layout) and
+     * passes it back from `onOrderChange`.
+     */
+    order?: string[];
+    /** The initial order when `order` is not controlled. Default: the order the tiles are written in. */
+    defaultOrder?: string[];
+    /** Called with the whole new order after a drop, a keyboard move or a move button. */
+    onOrderChange?: (order: string[]) => void;
+    /** Edit mode (controlled): tiles show a handle and can be reordered. */
+    editing?: boolean;
+    /** Edit mode at first, when `editing` is not controlled. */
+    defaultEditing?: boolean;
+    onEditingChange?: (editing: boolean) => void;
+    /** The "Edit layout" / "Done" button above the grid. `false` hides it, for an app that toggles `editing` itself. Default `true`. */
+    editButton?: boolean;
+    /**
+     * Columns by container width: `{ base: 1, md: 2, xl: 4 }`, the default
+     * (`md` is 768px, `xl` 1280px). A tile's span is held to the columns of
+     * its width.
+     */
+    columns?: DashboardColumns;
+    /** The space between tiles: `sm` 0.5rem, `md` 1rem (default), `lg` 1.5rem. */
+    gap?: ResponsiveGridGap;
+    /** Fill the holes a wide tile leaves by moving later, smaller tiles up. The visual order then differs from the tab order. */
+    dense?: boolean;
+};
+export type DashboardTileProps = Omit<ComponentProps<'div'>, 'title' | 'id'> & {
+    /** Names the tile in the order (`order` lists these ids). Unique in the grid. */
+    id: string;
+    /** A heading at the top of the tile (an `h3`), also its accessible name and the name of its handle. */
+    title?: ReactNode;
+    /** Columns the tile covers: a number, `'full'`, or one per width. Held to the grid's columns. */
+    span?: ResponsiveValue<GridSpan>;
+    /** Rows the tile covers (1 to 4), or one per width. */
+    rowSpan?: ResponsiveValue<GridRowSpan>;
+    /** Draws no card (border, background, padding) of its own: for a child that is a card already (`StatCard`, `Card`). */
+    plain?: boolean;
+    /** Names the tile for its handle and the announcements when `title` is not text. */
+    label?: string;
+};