themelia-react-ui 2.0.4 → 2.0.6

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

@@ -3,6 +3,18 @@ export type TopbarSidebarHeaderTheme = 'light' | 'dark';
 export type TopbarSidebarSide = 'left' | 'right';
 export type TopbarSidebarContentElement = 'main' | 'div';
 export type TopbarSidebarMobileSidebarMode = 'drawer' | 'inline';
+export type AppShellContentSurface = 'plain' | 'inset';
+export type AppShellSidebarPresentation = 'panel' | 'rail';
+export interface AppShellSidebarRegionProps {
+    /** Width of contextual navigation; defaults to the shared sidebar width. */
+    secondarySidebarWidth?: string;
+    /** Width of the opposite-side supporting panel. */
+    asideWidth?: string;
+    /** Primary navigation geometry, independent of its collapse state. */
+    sidebarPresentation?: AppShellSidebarPresentation;
+    secondarySidebarClassName?: string;
+    asideClassName?: string;
+}
 export interface TopbarSidebarLayoutSlots {
     /** Full header replacement inside the themed header region. */
     header?: ReactNode;
@@ -20,6 +32,10 @@ export interface TopbarSidebarLayoutSlots {
     headerEnd?: ReactNode;
     /** Sidebar column content. */
     sidebar?: ReactNode;
+    /** Contextual navigation next to the primary sidebar. */
+    secondarySidebar?: ReactNode;
+    /** Optional supporting panel on the opposite edge. */
+    aside?: ReactNode;
     /** Full content replacement; falls back to `children`. */
     content?: ReactNode;
 }
@@ -27,16 +43,18 @@ export type TopbarSidebarLayoutStyle = CSSProperties & {
     '--shell-header-height'?: string;
     '--shell-sidebar-width'?: string;
 };
-export interface TopbarSidebarLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface TopbarSidebarLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps {
     /** Page content rendered in the content column. */
     children?: ReactNode;
-    /** Header theme. Applies a `.light`/`.dark` token scope to the header so partials use ordinary tokens and invert against the header surface. */
+    /** Header theme. Omitted, the header follows the active theme. `light`/`dark` apply a token scope to the header so partials use ordinary tokens and invert against the header surface. */
     headerTheme?: TopbarSidebarHeaderTheme;
+    /** Inset paints the page on a card surface within the secondary shell canvas. */
+    contentSurface?: AppShellContentSurface;
     /** Sidebar side in the body grid. */
     sidebarSide?: TopbarSidebarSide;
-    /** Mobile sidebar behavior. `drawer` hides the body column below `md` so `SidebarTrigger` can open the sheet. */
+    /** `drawer` adapts navigation to an overlay. `inline` keeps both navigation regions docked; a rail remains beside its collapsible contextual sidebar. */
     mobileSidebarMode?: TopbarSidebarMobileSidebarMode;
-    /** Header height CSS value. Defaults to `var(--shell-header-height)`, whose root default is 4.5rem. */
+    /** Header height CSS value. Defaults to `var(--shell-header-height)`, whose root default is 4rem. */
     headerHeight?: string;
     /** Expanded sidebar column width CSS value. Defaults to `var(--shell-sidebar-width)`, whose root default is 16rem. */
     sidebarWidth?: string;
@@ -70,6 +88,10 @@ export type SidebarInsetSurface = 'inset' | 'flush';
 export interface SidebarInsetLayoutSlots {
     /** Sidebar column content, spanning the full page height. */
     sidebar?: ReactNode;
+    /** Contextual navigation beside the primary sidebar. */
+    secondarySidebar?: ReactNode;
+    /** Supporting panel on the opposite edge. */
+    aside?: ReactNode;
     /** Full toolbar replacement inside the content column. */
     toolbar?: ReactNode;
     /** Sidebar trigger, rendered at the start of the toolbar. */
@@ -81,13 +103,15 @@ export interface SidebarInsetLayoutSlots {
     /** Full content replacement; falls back to `children`. */
     content?: ReactNode;
 }
-export interface SidebarInsetLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+export interface SidebarInsetLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps {
     /** Page content rendered in the content column. */
     children?: ReactNode;
     /** Sidebar side. */
     sidebarSide?: SidebarInsetSide;
     /** How the content surface meets the sidebar. */
     surface?: SidebarInsetSurface;
+    /** `drawer` adapts navigation to an overlay. `inline` keeps both navigation regions docked; a rail remains beside its collapsible contextual sidebar. @default 'drawer' */
+    mobileSidebarMode?: TopbarSidebarMobileSidebarMode;
     /** Renders the toolbar row. Set `false` for a shell with no header chrome at all. */
     toolbar?: boolean;
     /** Expanded sidebar column width CSS value. */
@@ -121,18 +145,23 @@ export interface StackedLayoutSlots {
     headerEnd?: ReactNode;
     /** Secondary row under the header, usually tabs or a breadcrumb. */
     subheader?: ReactNode;
+    /** Optional supporting panel beside the page. */
+    aside?: ReactNode;
     /** Full content replacement; falls back to `children`. */
     content?: ReactNode;
 }
 export interface StackedLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Page content. */
     children?: ReactNode;
-    /** Header theme, matching `TopbarSidebarLayout`'s token-scope approach. */
+    /** Header theme. Omitted, the header follows the active theme; `light`/`dark` apply `TopbarSidebarLayout`'s token scope. */
     headerTheme?: TopbarSidebarHeaderTheme;
     /** Constrains the content to the shell's reading width, or lets it span. */
     contentWidth?: StackedContentWidth;
     /** Header height CSS value. */
     headerHeight?: string;
+    /** Width of the optional supporting panel. */
+    asideWidth?: string;
+    asideClassName?: string;
     /** Convenience logo slot. */
     logo?: ReactNode;
     /** Convenience navigation slot. */

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

@@ -1,5 +1,5 @@
 export { TopbarSidebarLayout } from './topbar-sidebar-layout';
-export type { TopbarSidebarContentElement, TopbarSidebarHeaderTheme, TopbarSidebarLayoutProps, TopbarSidebarLayoutSlots, TopbarSidebarLayoutStyle, TopbarSidebarSide, } from './app-shell.types';
+export type { AppShellContentSurface, AppShellSidebarPresentation, AppShellSidebarRegionProps, TopbarSidebarContentElement, TopbarSidebarHeaderTheme, TopbarSidebarLayoutProps, TopbarSidebarLayoutSlots, TopbarSidebarLayoutStyle, TopbarSidebarSide, } from './app-shell.types';
 export { SidebarInsetLayout } from './sidebar-inset-layout';
 export { StackedLayout } from './stacked-layout';
 export type { SidebarInsetContentElement, SidebarInsetLayoutProps, SidebarInsetLayoutSlots, SidebarInsetSide, SidebarInsetSurface, StackedContentElement, StackedContentWidth, StackedLayoutProps, StackedLayoutSlots, } from './app-shell.types';

package/dist/components/layout/app-shell/shell-regions.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import type { AppShellSidebarPresentation } from './app-shell.types';
+/** One surface recipe; the shell frames the page while Page owns its insets. */
+export declare const shellContentSurface: {
+    readonly plain: "bg-background text-foreground";
+    readonly inset: "bg-card text-card-foreground md:m-space-md md:overflow-hidden md:rounded-surface md:border md:border-border md:shadow-sm";
+};
+interface ShellRegionGridProps {
+    children: ReactNode;
+    sidebar?: ReactNode;
+    secondarySidebar?: ReactNode;
+    aside?: ReactNode;
+    side?: 'left' | 'right';
+    primaryWidth?: string;
+    secondaryWidth?: string;
+    asideWidth?: string;
+    presentation?: AppShellSidebarPresentation;
+    inlinePrimary?: boolean;
+    className?: string;
+    mainClassName?: string;
+    sidebarClassName?: string;
+    secondarySidebarClassName?: string;
+    asideClassName?: string;
+}
+/** Optional auto tracks collapse independently; the page always owns the flexible track. */
+export declare function ShellRegionGrid({ children, sidebar, secondarySidebar, aside, side, primaryWidth, secondaryWidth, asideWidth, presentation, inlinePrimary, className, mainClassName, sidebarClassName, secondarySidebarClassName, asideClassName }: ShellRegionGridProps): import("react").JSX.Element;
+export {};

package/dist/components/layout/app-shell/sidebar-inset-layout.d.ts

@@ -1,2 +1,2 @@
 import type { SidebarInsetLayoutProps } from './app-shell.types';
-export declare function SidebarInsetLayout({ children, sidebarSide, surface, toolbar, sidebarWidth, sidebar, sidebarTrigger, slots, contentAs: Content, className, sidebarClassName, toolbarClassName, contentClassName, style, ...props }: SidebarInsetLayoutProps): import("react").JSX.Element;
+export declare function SidebarInsetLayout({ children, sidebarSide, surface, mobileSidebarMode, toolbar, sidebarWidth, secondarySidebarWidth, asideWidth, sidebarPresentation, secondarySidebarClassName, asideClassName, sidebar, sidebarTrigger, slots, contentAs: Content, className, sidebarClassName, toolbarClassName, contentClassName, style, ...props }: SidebarInsetLayoutProps): import("react").JSX.Element;

package/dist/components/layout/app-shell/stacked-layout.d.ts

@@ -1,2 +1,2 @@
 import type { StackedLayoutProps } from './app-shell.types';
-export declare function StackedLayout({ children, headerTheme, contentWidth, headerHeight, logo, nav, slots, contentAs: Content, className, headerClassName, subheaderClassName, contentClassName, style, ...props }: StackedLayoutProps): import("react").JSX.Element;
+export declare function StackedLayout({ children, headerTheme, contentWidth, headerHeight, asideWidth, asideClassName, logo, nav, slots, contentAs: Content, className, headerClassName, subheaderClassName, contentClassName, style, ...props }: StackedLayoutProps): import("react").JSX.Element;

package/dist/components/layout/app-shell/topbar-sidebar-layout.d.ts

@@ -1,2 +1,2 @@
 import type { TopbarSidebarLayoutProps } from './app-shell.types';
-export declare function TopbarSidebarLayout({ children, headerTheme, sidebarSide, mobileSidebarMode, headerHeight, sidebarWidth, sidebarTrigger, logo, headerActions, sidebar, slots, contentAs: Content, className, headerClassName, headerInnerClassName, bodyClassName, sidebarClassName, contentClassName, style, ...props }: TopbarSidebarLayoutProps): import("react").JSX.Element;
+export declare function TopbarSidebarLayout({ children, headerTheme, contentSurface, sidebarSide, mobileSidebarMode, headerHeight, sidebarWidth, secondarySidebarWidth, asideWidth, sidebarPresentation, secondarySidebarClassName, asideClassName, sidebarTrigger, logo, headerActions, sidebar, slots, contentAs: Content, className, headerClassName, headerInnerClassName, bodyClassName, sidebarClassName, contentClassName, style, ...props }: TopbarSidebarLayoutProps): import("react").JSX.Element;

package/dist/components/layout/containers/two-column-layout.d.ts

@@ -20,6 +20,8 @@ export interface TwoColumnLayoutProps extends useRender.ComponentProps<'div'> {
     stickyAside?: boolean;
     /** Preserve viewport breakpoints by default, or adapt inside Container/PageViewport. */
     adaptTo?: 'viewport' | 'container';
+    /** Optional main/aside proportions; omission preserves the established flexible 2/1 split. */
+    ratio?: '7/5' | '8/4';
     /** Native attributes for each stable region. */
     slotProps?: TwoColumnLayoutSlotProps;
 }

package/dist/components/layout/header/header.recipes.d.ts

@@ -0,0 +1,6 @@
+/** Fixed-height inline rules align to header controls rather than stretching
+ * from the top edge of a flex row. Separator keeps its general stretch default. */
+export declare const headerInlineDividerAlignment = "[&_[data-slot=separator][data-orientation=vertical]]:self-center";
+/** One unread-count chip for header icon triggers. Counts state no status, so it
+ * takes the neutral solid role; it floats over the icon, so it is opaque. */
+export declare const headerCountBadge = "pointer-events-none absolute -end-1 -top-1 flex h-4.5 min-w-4.5 items-center justify-center rounded-full bg-foreground px-space-xs text-background tabular-nums";

package/dist/components/layout/header/header.types.d.ts

@@ -13,8 +13,9 @@ export interface HeaderBreadcrumbsProps extends LayoutNavigationAdapter {
     breadcrumbs?: BreadcrumbItem[];
     /** Root entry prepended to the trail. */
     homeBreadcrumb?: BreadcrumbItem | null;
-    /** Renders the sidebar collapse control. */
+    /** Renders the sidebar control when a provider or a trigger slot is present. @default true */
     showSidebarTrigger?: boolean;
+    /** Custom trigger content. Can be used without a sidebar provider. */
     triggerSlot?: ReactNode;
     className?: string;
 }
@@ -164,15 +165,15 @@ export interface HeaderUserMenuStrings {
 }
 export declare const defaultHeaderUserMenuStrings: HeaderUserMenuStrings;
 export interface HeaderSlots {
-    /** Leading brand/logo region before breadcrumbs. */
+    /** Leading brand/logo before breadcrumbs, visible from the 2xl/app-header container width (42rem by default). Use left for identity that must remain visible at narrow widths. */
     brand?: ReactNode;
-    /** Replaces the breadcrumb/sidebar-trigger region. */
+    /** Replaces the breadcrumb/sidebar-trigger region, rendered only while showBreadcrumbs is true. */
     breadcrumbs?: ReactNode;
-    /** Leading content after breadcrumbs. */
+    /** Leading content after breadcrumbs; always rendered when supplied, including narrow container widths. The app owns compact content and overflow. */
     left?: ReactNode;
-    /** Center content, usually search or a scope switcher. */
+    /** Optional center content, usually search, visible from the 3xl/app-header container width (48rem by default). Essential navigation needs a narrow-width alternative in left or right. */
     center?: ReactNode;
-    /** Trailing content, usually notifications/user menu/actions. */
+    /** Trailing content, usually tools/account actions; always rendered when supplied and wraps at narrow widths. Its children own their responsive behavior. */
     right?: ReactNode;
 }
 export interface HeaderProps extends LayoutNavigationAdapter, HTMLAttributes<HTMLElement> {
@@ -182,9 +183,9 @@ export interface HeaderProps extends LayoutNavigationAdapter, HTMLAttributes<HTM
     breadcrumbs?: BreadcrumbItem[];
     /** Root entry prepended to the trail. */
     homeBreadcrumb?: BreadcrumbItem | null;
-    /** Renders the sidebar collapse control. */
+    /** Renders the sidebar control when a sidebar provider is present. @default true */
     showSidebarTrigger?: boolean;
-    /** Replaces individual regions of the shell. */
+    /** Composes shell regions by container width: brand appears from 2xl/app-header (42rem default), center from 3xl/app-header (48rem default); left and right are always rendered when supplied. Keep essential narrow-width identity/navigation in left or right and supply compact/overflow behavior. */
     slots?: HeaderSlots;
     className?: string;
     /** Merged onto the content region. */

package/dist/components/layout/layout.types.d.ts

@@ -5,13 +5,13 @@
  * router package. Navigation is delegated to the consumer through
  * `renderLink`.
  */
-import type { ComponentType, HTMLAttributes, MouseEvent, ReactNode } from 'react';
+import type { AriaAttributes, ComponentType, HTMLAttributes, MouseEvent, ReactNode } from 'react';
 /** Native region props, including strongly typed consumer `data-*` hooks. */
 export type LayoutSlotAttributes<ElementType extends HTMLElement> = HTMLAttributes<ElementType> & {
     [Key in `data-${string}`]?: string | number | boolean | undefined;
 };
 export interface LayoutLinkRenderProps {
-    /** Destination URL. When omitted, render non-interactive content. */
+    /** Destination URL. Without a URL, the default renders a button when onClick is supplied. */
     href?: string;
     children: ReactNode;
     className?: string;
@@ -19,6 +19,8 @@ export interface LayoutLinkRenderProps {
     rel?: string;
     onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
     'aria-label'?: string;
+    /** Current-page state supplied by a navigation owner. */
+    'aria-current'?: AriaAttributes['aria-current'];
     /** Consumer hint for active styling; renderers may ignore it. */
     active?: boolean;
     /** Consumer hint to render as muted/non-interactive. */
@@ -40,7 +42,7 @@ export interface LayoutNavigationAdapter {
     /** Renderer for framework-native links. */
     renderLink?: LayoutLinkRenderer;
 }
-/** Default link renderer — native anchor with disabled fallback. */
+/** Renders native links, callback buttons and inert entries. */
 export declare const defaultRenderLink: LayoutLinkRenderer;
 /** Resolve the consumer renderer or the native-anchor default. */
 export declare function resolveLayoutLinkRenderer({ renderLink, }?: LayoutNavigationAdapter): LayoutLinkRenderer;

package/dist/components/layout/navigation/section-nav/section-nav.d.ts

@@ -2,6 +2,11 @@
  * SectionNav — sticky in-page anchor nav. Pass a list of section ids; the active one
  * is tracked via IntersectionObserver and the matching item is highlighted. Click to
  * scroll to that section. Pure JS — no router required.
+ *
+ * A click owns the current state: the clicked section stays current while the smooth
+ * scroll it started passes other sections, after that scroll settles (including when
+ * the last sections are too short to reach the top), and until the reader scrolls
+ * again. Only then does the observer resume.
  */
 import { type ComponentPropsWithoutRef } from 'react';
 import type { LucideIcon } from 'lucide-react';

package/dist/components/layout/navigation/side-nav.d.ts

@@ -10,6 +10,7 @@
 import { type LucideIcon } from 'lucide-react';
 import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 import { type StringsProp } from '../../../lib/strings';
+import type { LayoutNavigationAdapter } from '../layout.types';
 export interface SideNavStrings {
     navigationLabel: string;
 }
@@ -36,8 +37,8 @@ export interface SideNavGroup {
     defaultCollapsed?: boolean;
     collapsible?: boolean;
 }
-interface SideNavSharedProps extends Omit<ComponentPropsWithoutRef<'nav'>, 'children'> {
-    /** Path of the active route, used to mark the current entry. */
+interface SideNavSharedProps extends Omit<ComponentPropsWithoutRef<'nav'>, 'children'>, LayoutNavigationAdapter {
+    /** Path supplied by the app. Omit it to leave every entry unmarked. */
     currentPath?: string;
     itemClassName?: string;
     activeItemClassName?: string;

package/dist/components/layout/normalize-layout-path.d.ts

@@ -0,0 +1 @@
+export declare function normalizeLayoutPath(rawUrl: string): string;

package/dist/components/layout/page/index.d.ts

@@ -1,4 +1,5 @@
 export { Page } from './page';
 export { PageHeader } from './partials/page-header';
 export { PageActions } from './partials/page-actions';
-export { defaultPageActionsStrings, type PageHeaderAction, type PageHeaderProps, type PageHeaderSlots, type PageHeaderTabs, type PageActionsProps, type PageActionsDisplay, type PageAction, type PageActionContext, type PageActionsStrings, type PageProps, type PageSlotProps, } from './page.types';
+export { defaultPageActionsStrings, type PageHeaderAction, type PageHeaderProps, type PageHeaderSlots, type PageHeaderRenderContext, type PageHeaderRenderSlot, type PageHeaderTabs, type PageActionsProps, type PageActionsDisplay, type PageAction, type PageActionContext, type PageActionsStrings, type PageProps, type PageSlotProps, type PageSlots, } from './page.types';
+export { defaultPageStrings, type PageStrings } from './page.strings';

package/dist/components/layout/page/page.d.ts

@@ -1,2 +1,3 @@
 import type { PageProps } from './page.types';
+/** Route containment, header, lifecycle states and optional secondary context, without owning scrolling. */
 export declare const Page: import("react").ForwardRefExoticComponent<Omit<PageProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/layout/page/page.strings.d.ts

@@ -0,0 +1,11 @@
+/** Copy for Page's primary-body lifecycle states. */
+export interface PageStrings {
+    loadingLabel: string;
+    loadingDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    retryLabel: string;
+    emptyTitle: string;
+    emptyDescription: string;
+}
+export declare const defaultPageStrings: PageStrings;

package/dist/components/layout/page/page.types.d.ts

@@ -13,6 +13,8 @@ import type { BadgeTone } from '../../base/badge';
 import type { ActionPresentation } from '../../../lib/action-presentation';
 import type { PageHeaderAction } from '../../base/navigation/page-header';
 import type { OverflowTabItem } from '../../base/navigation';
+import type { TwoColumnLayoutProps } from '../containers';
+import type { PageStrings } from './page.strings';
 export interface PageTitleBadge {
     /** Display label. */
     label: ReactNode;
@@ -37,15 +39,25 @@ export interface PageHeaderTabs {
     /** Label of the trigger that holds tabs which do not fit. Default: `'More'`. */
     moreLabel?: string;
 }
+export interface PageHeaderRenderContext {
+    /** The framework-neutral link renderer used by this header. */
+    renderLink: LayoutLinkRenderer;
+    /** Existing content for this position; actions includes the responsive command row. */
+    defaultContent: ReactNode;
+}
+/** A content node, or a render callback that can keep or replace its default content. */
+export type PageHeaderRenderSlot = ReactNode | ((context: PageHeaderRenderContext) => ReactNode);
 export interface PageHeaderSlots {
-    /** Replaces the leading back control entirely. */
+    /** @deprecated Use backHref/onBack for navigation. Retained as a custom back-control escape hatch. */
     back?: ReactNode;
-    /** Additional content before the title line. */
-    beforeTitle?: ReactNode;
-    /** Additional content after the description. */
-    afterDescription?: ReactNode;
-    /** Replaces the trailing actions region, including role-based commands. */
-    actions?: ReactNode;
+    /** Context above the title, such as breadcrumbs. */
+    beforeTitle?: PageHeaderRenderSlot;
+    /** Content beside the title, such as a status or count. */
+    titleSuffix?: PageHeaderRenderSlot;
+    /** Context below the description. Compose metadata or other content here. */
+    afterDescription?: PageHeaderRenderSlot;
+    /** Keep, wrap or replace defaultContent's responsive command row. */
+    actions?: PageHeaderRenderSlot;
 }
 export interface PageHeaderProps extends LayoutNavigationAdapter {
     /** Surface title. */
@@ -56,35 +68,42 @@ export interface PageHeaderProps extends LayoutNavigationAdapter {
     textGap?: TextGap;
     /** Semantic heading level for the title. Defaults to `h1`, the route's main heading; use `h2` when the page sits inside another titled page. */
     headingTag?: HeadingTag;
-    /** Optional decorative icon rendered before the title. Pass a Lucide icon component. */
+    /** @deprecated Compose custom title content with slots.titleSuffix or a React-node title. */
     titleIcon?: ComponentType<{
         className?: string;
     }>;
-    /** Optional link target for the title icon. Uses the same framework-neutral renderer as `backHref`. */
+    /** @deprecated Compose a linked item in a render slot using its renderLink context. */
     titleIconHref?: string;
-    /** Optional click handler for the title icon when it should behave like an action. */
+    /** @deprecated Compose a command in slots.actions or describe it with primaryAction/secondaryActions. */
     onTitleIconClick?: () => void;
-    /** Accessible label for linked/clickable title icons. */
+    /** @deprecated Accessible name for the compatibility title-icon control. */
     titleIconLabel?: string;
     /** Destination for the back control. */
     backHref?: string;
     onBack?: () => void;
     /** Copy for the back control. */
     backLabel?: string;
-    /** Chips shown beside the page title. */
+    /** @deprecated Render title content with slots.titleSuffix. Retained for existing badge definitions. */
     titleBadges?: PageTitleBadge[];
     /**
      * The page's one main command: a solid primary button after the secondary
-     * commands, visible at every width.
+     * commands. Compact headers place it first in the More actions menu.
      */
     primaryAction?: PageHeaderAction;
     /**
      * Supporting commands in priority order. The first two render as outline
      * buttons before the primary command; the rest, and every destructive
      * command, move into the More actions menu, which always closes the row.
-     * Below `sm`, all secondary commands collapse into that menu.
+     * Below 40rem of header width, all commands collapse into that menu.
      */
     secondaryActions?: readonly PageHeaderAction[];
+    /**
+     * How many routine secondary commands render as outline buttons on wide
+     * headers; later ones join the More actions menu. Use `1` or `0` when long
+     * labels beside the primary command would crowd the header; `Infinity`
+     * keeps every routine command inline. @default 2
+     */
+    maxVisibleSecondaryActions?: number;
     /** Accessible name of the More actions menu trigger. */
     moreActionsLabel?: string;
     /**
@@ -94,8 +113,7 @@ export interface PageHeaderProps extends LayoutNavigationAdapter {
      */
     tabs?: PageHeaderTabs;
     /**
-     * Custom controls before the role-based commands, such as a period select.
-     * Prefer `primaryAction` and `secondaryActions` for commands.
+     * @deprecated Customize commands with slots.actions; put other controls in Page toolbar.
      */
     actions?: ReactNode;
     /** Replaces individual regions of the shell. */
@@ -173,11 +191,24 @@ export interface PageActionsProps extends LayoutNavigationAdapter {
 export interface PageSlotProps {
     /** Native attributes merged onto the page body region. */
     body?: LayoutSlotAttributes<HTMLDivElement>;
+    aside?: LayoutSlotAttributes<HTMLElement>;
+    toolbar?: LayoutSlotAttributes<HTMLDivElement>;
+    footer?: LayoutSlotAttributes<HTMLDivElement>;
+}
+export interface PageSlots {
+    /** Replaces the generated PageHeader. */
+    header?: ReactNode;
+    toolbar?: ReactNode;
+    aside?: ReactNode;
+    footer?: ReactNode;
+    loading?: ReactNode;
+    error?: ReactNode;
+    empty?: ReactNode;
 }
 export interface PageProps extends LayoutNavigationAdapter, Omit<ContainerProps, 'children'> {
     /** Header region of the shell. */
     header?: PageHeaderProps;
-    /** Maximum content width. Explicit values override narrow. Defaults to `lg`. */
+    /** Explicit width wins; otherwise narrow uses md, aside uses xl, and a single column uses lg. */
     maxWidth?: ContainerMaxWidth;
     /** Center one resource or form at the existing `md` content measure. */
     narrow?: boolean;
@@ -185,6 +216,27 @@ export interface PageProps extends LayoutNavigationAdapter, Omit<ContainerProps,
     gutter?: ContainerGutter;
     /** Block padding around the whole page. Defaults to `lg`, independent of gutter. */
     padding?: ContainerGutter;
+    /** Secondary context beside the primary body, adapting to the available container width. */
+    aside?: ReactNode;
+    /** Main/aside proportions. Defaults to 7/5. */
+    asideRatio?: TwoColumnLayoutProps['ratio'];
+    stickyAside?: boolean;
+    /** Query controls or context between header and body. */
+    toolbar?: ReactNode;
+    /** Content above the header. */
+    beforeHeader?: ReactNode;
+    /** Compatible toolbar fallback when toolbar and slots.toolbar are omitted. */
+    afterHeader?: ReactNode;
+    /** Replaces only the primary body; header, toolbar and aside remain mounted. */
+    loading?: boolean;
+    error?: ReactNode | Error;
+    onRetry?: () => void;
+    empty?: boolean;
+    emptySlot?: ReactNode;
+    /** Region overrides take precedence over direct props. */
+    slots?: PageSlots;
+    /** Copy for the default loading, error and empty states. */
+    strings?: StringsProp<PageStrings>;
     children?: ReactNode;
     /** Native attributes for stable page regions. */
     slotProps?: PageSlotProps;

package/dist/components/layout/page/partials/page-header.d.ts

@@ -1,2 +1,2 @@
 import type { PageHeaderProps } from '../page.types';
-export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, primaryAction, secondaryActions, moreActionsLabel, tabs, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;
+export declare function PageHeader({ title, description, textGap, headingTag, titleIcon: TitleIcon, titleIconHref, onTitleIconClick, titleIconLabel, backHref, onBack, backLabel, titleBadges, primaryAction, secondaryActions, maxVisibleSecondaryActions, moreActionsLabel, tabs, actions, slots, renderLink, className, contentClassName, actionsClassName, titleClassName, titleIconClassName, descriptionClassName, }: PageHeaderProps): import("react").JSX.Element;

package/dist/components/layout/settings/settings.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactNode } from 'react';
+import { type ComponentType, type ReactNode } from 'react';
 import { type PageHeaderAction } from '../../base/navigation/page-header/page-header-commands';
 import { type StringsProp } from '../../../lib/strings';
 import { type LayoutNavigationAdapter } from '../layout.types';
@@ -51,7 +51,7 @@ export interface AsideNavShellProps extends LayoutNavigationAdapter {
      * render before the role-based commands.
      */
     actions?: ReactNode;
-    /** The page's one main command: a solid primary button, visible at every width. */
+    /** The page's one main command: a solid primary button, available in the compact header menu. */
     primaryAction?: PageHeaderAction;
     /**
      * Supporting commands in priority order, as in Page headers: the first two
@@ -59,6 +59,13 @@ export interface AsideNavShellProps extends LayoutNavigationAdapter {
      * destructive command, move into the More actions menu, which closes the row.
      */
     secondaryActions?: readonly PageHeaderAction[];
+    /**
+     * How many routine secondary commands render as outline buttons on wide
+     * headers; later ones join the More actions menu. Use `1` or `0` when long
+     * labels beside the primary command would crowd the header; `Infinity`
+     * keeps every routine command inline. @default 2
+     */
+    maxVisibleSecondaryActions?: number;
     /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
     moreActionsLabel?: string;
     /** Content below the body. */
@@ -72,7 +79,7 @@ export interface AsideNavShellProps extends LayoutNavigationAdapter {
     strings?: StringsProp<AsideNavShellStrings>;
 }
 export type SettingsShellProps = AsideNavShellProps;
-export declare function AsideNavShell({ title, description, groups, currentId, currentPath, children, aside, actions, primaryAction, secondaryActions, moreActionsLabel, footer, className, navClassName, contentClassName, renderLink, strings: stringsProp, }: AsideNavShellProps): import("react").JSX.Element;
+export declare function AsideNavShell({ title, description, groups, currentId, currentPath, children, aside, actions, primaryAction, secondaryActions, maxVisibleSecondaryActions, moreActionsLabel, footer, className, navClassName, contentClassName, renderLink, strings: stringsProp, }: AsideNavShellProps): import("react").JSX.Element;
 export declare namespace AsideNavShell {
     var displayName: string;
 }

package/dist/components/layout/sidebar/app-sidebar.d.ts

@@ -4,4 +4,4 @@
  */
 import * as React from 'react';
 import type { AppSidebarProps } from './sidebar.types';
-export declare function AppSidebar({ navigationGroups, footerNavItems, footerLabel, logo, collapsedLogo, workspaceLinks, workspaceStrings, workspaceContentClassName, headerClassName, logoClassName, iconMap, currentUrl, liveBadges, showBadges, menuDensity, renderLink, loading, collapsible, variant, side, className, surfaceClassName, contentClassName, slots, renderItem, searchable, searchValue, defaultSearchValue, onSearchValueChange, strings: stringsProp, expandedItems, defaultExpandedItems, onExpandedItemsChange, }: AppSidebarProps): React.JSX.Element;
+export declare function AppSidebar({ navigationGroups, 'aria-label': navigationLabel, footerNavItems, footerLabel, logo, collapsedLogo, workspaceLinks, workspaceStrings, workspaceContentClassName, headerClassName, logoClassName, iconMap, currentUrl, closeDrawerOnNavigate, liveBadges, showBadges, menuDensity, renderLink, loading, collapsible, panelId, surface, variant, side, className, surfaceClassName, contentClassName, slots, renderItem, renderItemContent, searchable, searchValue, defaultSearchValue, onSearchValueChange, strings: stringsProp, expandedItems, defaultExpandedItems, onExpandedItemsChange, }: AppSidebarProps): React.JSX.Element;

package/dist/components/layout/sidebar/components/sidebar-grouped-navigation.d.ts

@@ -1,4 +1,4 @@
 /** Grouped navigation uses public disclosure and sidebar anatomy; routing stays app-owned. */
 import * as React from 'react';
 import { type SidebarGroupedNavigationProps } from '../sidebar.types';
-export declare function SidebarGroupedNavigation({ navigationByGroups, currentUrl, iconMap, liveBadges, showBadges, renderLink, emptySlot, renderItem, className, menuDensity, expandedItems, defaultExpandedItems, onExpandedItemsChange, searchValue, strings: stringsProp, }: SidebarGroupedNavigationProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null;
+export declare function SidebarGroupedNavigation({ navigationByGroups, currentUrl, iconMap, liveBadges, showBadges, renderLink, emptySlot, renderItem, renderItemContent, className, menuDensity, expandedItems, defaultExpandedItems, onExpandedItemsChange, searchValue, strings: stringsProp, }: SidebarGroupedNavigationProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null;

package/dist/components/layout/sidebar/components/sidebar-navigation.d.ts

@@ -1,4 +1,4 @@
 /** SidebarNavigation — flat, framework-neutral sidebar nav list. */
 import * as React from 'react';
 import type { SidebarFlatNavigationProps } from '../sidebar.types';
-export declare function SidebarNavigation({ items, label, currentUrl, iconMap, liveBadges, showBadges, renderLink, renderItem, className, menuDensity, }: SidebarFlatNavigationProps): React.JSX.Element;
+export declare function SidebarNavigation({ items, label, currentUrl, iconMap, liveBadges, showBadges, renderLink, renderItem, renderItemContent, className, menuDensity, }: SidebarFlatNavigationProps): React.JSX.Element;

package/dist/components/layout/sidebar/index.d.ts

@@ -1,6 +1,7 @@
 export { LayoutSidebar, type LayoutSidebarProps } from './sidebar';
 export { LayoutSidebarProvider, useLayoutSidebar, type LayoutSidebarContext, type LayoutSidebarProviderProps, } from './sidebar.context';
 export { AppSidebar } from './app-sidebar';
+export { SidebarNavigationRail, type SidebarNavigationRailItem, type SidebarNavigationRailProps } from './sidebar-navigation-rail';
 export { SidebarLogo, type SidebarLogoProps } from './components/sidebar-logo';
 export { SidebarWorkspaceDropdown } from './components/sidebar-workspace-dropdown';
 export { SidebarNavigation } from './components/sidebar-navigation';
@@ -8,4 +9,4 @@ export { SidebarGroupedNavigation } from './components/sidebar-grouped-navigatio
 export { SidebarNavigationFooter } from './components/sidebar-navigation-footer';
 export { SidebarNavigationUser, defaultSidebarNavigationUserStrings, type SidebarNavigationUserProps, type SidebarNavigationUserStrings, } from './components/sidebar-navigation-user';
 export { toPath, isPathMatch, getNavLabel, getNavKey, DynamicIcon as SidebarIcon, type DynamicIconProps as SidebarIconProps, NavBadge, resolveNavBadge, } from './sidebar.utils';
-export { defaultSidebarWorkspaceDropdownStrings, defaultSidebarNavigationStrings, type SidebarNavigationStrings, type SidebarExpansionProps, type AppSidebarProps, type SidebarNavItem, type SidebarFlatNavItem, type SidebarRenderItemContext, type SidebarSlots, type SidebarFlatNavigationProps, type SidebarGroupedNavigationProps, type SidebarFooterNavigationItem, type SidebarNavigationFooterProps, type WorkspaceLink, type SidebarWorkspaceDropdownProps, type SidebarWorkspaceDropdownStrings, } from './sidebar.types';
+export { defaultSidebarWorkspaceDropdownStrings, defaultSidebarNavigationStrings, type SidebarNavigationStrings, type SidebarExpansionProps, type AppSidebarProps, type SidebarNavItem, type SidebarNavigationGroup, type SidebarNavigationGroups, type SidebarFlatNavItem, type SidebarRenderItemContext, type SidebarRenderItemContentContext, type SidebarSlotContext, type SidebarSlot, type SidebarSlots, type SidebarFlatNavigationProps, type SidebarGroupedNavigationProps, type SidebarFooterNavigationItem, type SidebarNavigationFooterProps, type WorkspaceLink, type SidebarWorkspaceDropdownProps, type SidebarWorkspaceDropdownStrings, } from './sidebar.types';

package/dist/components/layout/sidebar/sidebar-navigation-rail.d.ts

@@ -0,0 +1,38 @@
+/** Primary area navigation, distinct from SidebarRail's collapse affordance. */
+import type { ComponentType } from 'react';
+import type { LayoutIconSource, LayoutNavigationAdapter } from '../layout.types';
+import { type LayoutSidebarProps } from './sidebar';
+import type { SidebarFlatNavItem, SidebarSlot } from './sidebar.types';
+export type SidebarNavigationRailItem = SidebarFlatNavItem & {
+    /** Informative area icon; the full label remains accessible. */
+    icon: LayoutIconSource;
+} & ({
+    id: string;
+} | {
+    handle: string;
+});
+export interface SidebarNavigationRailProps extends Omit<LayoutSidebarProps, 'children' | 'collapsible'>, LayoutNavigationAdapter {
+    items: readonly SidebarNavigationRailItem[];
+    /** Selected item id (or its legacy handle). Controlled. */
+    value?: string;
+    onValueChange?: (id: string) => void;
+    /** Used for native current-route indication when value is omitted. */
+    currentUrl?: string;
+    /** Close this already-open drawer when currentUrl, or the fallback value, changes. @default true */
+    closeDrawerOnNavigate?: boolean;
+    iconMap?: Record<string, ComponentType<{
+        className?: string;
+    }>>;
+    /** Structural content seams. Header/footer stay pinned; navigation additions scroll. The rail owns each region's insets. */
+    slots?: {
+        header?: SidebarSlot;
+        beforeNavigation?: SidebarSlot;
+        afterNavigation?: SidebarSlot;
+        footer?: SidebarSlot;
+    };
+    /** The rail stays visible by default; offcanvas makes the entire rail hideable. */
+    collapsible?: 'none' | 'offcanvas';
+    /** Accessible name for this navigation region. @default 'Primary navigation' */
+    'aria-label'?: string;
+}
+export declare function SidebarNavigationRail({ items, value, onValueChange, currentUrl, closeDrawerOnNavigate, renderLink, iconMap, slots, collapsible, 'aria-label': ariaLabel, className, surface, surfaceClassName, style, side, panelId, ...props }: SidebarNavigationRailProps): import("react").JSX.Element;