themelia-react-ui 2.0.5 → 3.0.0

package/dist/components/features/table/table.types.d.ts

@@ -7,6 +7,12 @@ declare module '@tanstack/react-table' {
     interface ColumnMeta<TData extends RowData, TValue> {
         /** Menu alignment against the trigger. */
         align?: 'start' | 'center' | 'end';
+        /**
+         * Plain-text name of the column for the Columns menu and the sort and
+         * resize control names. Set it when `header` is a function or element,
+         * which cannot be read as text.
+         */
+        label?: string;
     }
 }
 export type PageChangeHandler = (page: number, url: string, currentUrl: string) => void;
@@ -15,14 +21,17 @@ export interface ServerPaginationProps {
     pagination: PaginationType;
     /**
      * Fired with the requested page, its URL, and the base path. The library
-     * never navigates on its own; without this a page click is a no-op and only
-     * the anchor's `href` remains as the no-JS fallback.
+     * never navigates on its own; without this a plain click is a no-op. Each
+     * link still carries its `href`, so a modified click (new tab or window)
+     * and a no-JS visit reach the page through the browser.
      */
     onPageChange?: PageChangeHandler;
     /** Query-string parameter used to build each page link's `href`. Default: `'page'`. */
     pageQueryKey?: string;
     /** Overrides the pagination copy. */
     labels?: PaginationLabels;
+    /** Merged onto the outermost node. */
+    className?: string;
 }
 export interface TableAction<TData> extends Omit<ActionPresentation, 'visible' | 'disabled'> {
     /** Optional stable identifier for keys */
@@ -72,6 +81,10 @@ export interface DataTablePaginationStrings extends ExistingRequiredPaginationLa
     to: string;
 }
 export interface DataTableStrings {
+    /** Copy announced while the table body is loading. Optional for existing dictionaries. */
+    loading?: {
+        label: string;
+    };
     /** Shown in place of the collection when it has no entries. */
     emptyState: {
         message: string;
@@ -109,8 +122,15 @@ export interface DataTableStrings {
     pagination: DataTablePaginationStrings;
     selection: {
         summary: (selected: number, total: number) => string;
-        row: (index: number) => string;
+        /**
+         * Accessible name of a row's checkbox. Receives the row's zero-based
+         * position among the rows on screen (after sorting and filtering) and
+         * its record, so a row can be named by its content.
+         */
+        row: (index: number, record?: unknown) => string;
         selectAll: string;
+        /** Names the checkbox column when only one row can be selected, so there is no select-all control. */
+        columnLabel?: string;
         clear: string;
         /** Accessible name of the selected-row action region. */
         label?: string;
@@ -128,6 +148,7 @@ export interface DataTableStrings {
     };
 }
 export type DataTableStringsOverride = Partial<{
+    loading: Partial<NonNullable<DataTableStrings['loading']>>;
     /** Shown in place of the collection when it has no entries. */
     emptyState: Partial<DataTableStrings['emptyState']>;
     /** Overflow menu for the surface as a whole. */
@@ -168,10 +189,14 @@ export interface DataTableToolbarProps<TData> {
     labelVisibility?: 'responsive' | 'hidden';
     /** Overrides this surface's own copy. */
     strings?: DataTableStrings;
+    /** Merged onto the toolbar's outermost node. */
+    className?: string;
 }
 export interface DataTableSelectionToolbarContext<TData extends object> {
     table: Table<TData>;
+    /** Selected records available in the current `data` prop. */
     selectedRows: TData[];
+    /** Number of selected IDs, including selections outside the current page. */
     selectedRowCount: number;
     /** `totalRowCount` when supplied, else `pagination.total`, else the rows in `data`. */
     totalRowCount: number;
@@ -221,7 +246,8 @@ export interface DataTableProps<TData extends object, TValue> {
      * 1. Regular array: `columns={myColumns}`
      * 2. Tuple pattern with auto-memoization: `columns={[getColumns(t, actions), [t, actions]]}`
      *
-     * The tuple pattern eliminates the need for manual useMemo on the page level.
+     * The tuple keeps its definitions until the dependencies change. Include
+     * every value read by the definitions, including their cell callbacks.
      *
      * @example
      * // Pattern 1: Regular (requires manual memoization)
@@ -235,22 +261,20 @@ export interface DataTableProps<TData extends object, TValue> {
     columns: ColumnDef<TData, TValue>[] | [ColumnDef<TData, TValue>[], React.DependencyList];
     /** Records to render. */
     data: TData[];
+    /** Replaces body rows with placeholders while preserving headers and table state. */
+    loading?: boolean;
+    /** Number of placeholder rows while loading. Defaults to 6, capped at 20. */
+    loadingRows?: number;
     /** Banded headers spanning several columns, drawn above the header row. */
     columnGroups?: ColumnGroup[];
     /** Enables column sorting. */
     enableSorting?: boolean;
-    /** Enables the toolbar's filter input. Pair with `filterColumn`. */
-    enableFiltering?: boolean;
-    /** Renders the pagination footer. */
-    enablePagination?: boolean;
     /** Lets the user drag column edges to resize. */
     enableResizing?: boolean;
     /** Adds the selection checkbox column. */
     enableRowSelection?: boolean;
     /** Allows more than one row to be selected at a time. */
     enableMultiRowSelection?: boolean;
-    /** Lets selecting a parent row also select its expanded sub-rows. */
-    enableSubRowSelection?: boolean;
     /** Adds the toolbar control for hiding and showing columns. */
     enableColumnVisibility?: boolean;
     /** Controlled full-screen state. */
@@ -261,23 +285,20 @@ export interface DataTableProps<TData extends object, TValue> {
     onFullscreenChange?: (fullscreen: boolean) => void;
     /** Adds the toolbar control for entering and leaving full screen. */
     showFullscreenToggle?: boolean;
-    /**
-     * The consumer owns paging — the table renders the page it is given and does
-     * not slice `data` itself. Set this whenever pages come from the server.
-     */
-    manualPagination?: boolean;
     /**
      * The consumer owns sorting — the table reports intent through its sort
      * state and does not reorder `data` itself. Set this for server-side sorts.
      */
     manualSorting?: boolean;
-    /** Enables the underlying table library's debug logging. Development only. */
-    debugMode?: boolean;
     /** Pins the header row while the body scrolls. */
     stickyHeader?: boolean;
     /** Pins the toolbar while the body scrolls. */
     stickyToolbar?: boolean;
-    /** Pins the first column while the table scrolls horizontally. */
+    /**
+     * Pins the first data column while the table scrolls horizontally. With
+     * `enableRowSelection` the checkbox column and the first data column pin as
+     * a pair, so the identifying column stays in view beside its checkbox.
+     */
     stickyFirstColumn?: boolean;
     /** Caps the scrollable body height. A number is treated as pixels. */
     maxBodyHeight?: number | string;
@@ -286,9 +307,7 @@ export interface DataTableProps<TData extends object, TValue> {
      * than the page. The parent must have a resolved height for this to apply.
      */
     fillAvailableHeight?: boolean;
-    /** Copy shown when `data` is empty. */
-    emptyStateMessage?: string;
-    /** Control offered alongside the empty message — usually a create action. */
+    /** Control offered alongside the empty message (`strings.emptyState.message`), usually a create action. */
     emptyStateAction?: React.ReactNode;
     /** Merged onto the outermost node. */
     className?: string;
@@ -306,10 +325,12 @@ export interface DataTableProps<TData extends object, TValue> {
     tableContainerClassName?: string;
     /** Overrides this surface's own copy. */
     strings?: DataTableStringsOverride;
-    /** Column id the toolbar's filter input searches. Required for `enableFiltering`. */
+    /**
+     * Column id the toolbar's search input filters. Setting it shows the input
+     * and filters the loaded rows by that column; its placeholder is
+     * `strings.filter.searchPlaceholder`.
+     */
     filterColumn?: string;
-    /** Placeholder for the toolbar's filter input. */
-    filterPlaceholder?: string;
     /** Content at the start of the toolbar row, before the built-in controls. */
     topbarContent?: React.ReactNode;
     /** Right-side table utility slot rendered beside column/full-screen controls. */
@@ -364,8 +385,12 @@ export interface DataTableProps<TData extends object, TValue> {
      * `onClick` and route with your own router.
      */
     rowActions?: TableAction<TData>[] | ((row: TData) => TableAction<TData>[]);
-    /** Optional label for the row actions trigger */
-    rowActionsMenuLabel?: string | ((row: TData) => string);
+    /**
+     * Names each row's actions trigger from its record, for example
+     * `(order) => \`Actions for ${order.number}\``. One label for every row is
+     * `strings.actions.menuLabel`.
+     */
+    rowActionsMenuLabel?: (row: TData) => string;
     /** Display mode for row actions. Default: 'menu' (preserve existing) */
     rowActionsDisplayMode?: 'menu' | 'inline' | 'auto';
     /** Breakpoint in px for auto display mode. Default: 1040. */
@@ -408,30 +433,43 @@ export interface DataTableProps<TData extends object, TValue> {
     rowSelection?: RowSelectionState;
     /** Controlled sorting state. */
     sorting?: SortingState;
-    /** Initial sorting state for an uncontrolled table. */
-    defaultSorting?: SortingState;
     /** Controlled column visibility state. */
     columnVisibility?: VisibilityState;
-    /** Initial column visibility for an uncontrolled table. Explicit values override persisted state. */
-    defaultColumnVisibility?: VisibilityState;
     /**
-     * Starting state for an uncontrolled table, applied once on mount. The
-     * dedicated `default*` props take precedence over the matching keys here.
+     * Which side wins when `storageKey` holds a value for a column that also
+     * has an explicit default in `initialState.columnVisibility`.
+     *
+     * - `'defaults'` (default, the 2.0 behaviour): the explicit default wins on
+     *   every mount, so a user's change to such a column does not survive a
+     *   reload. The whole visibility state is stored.
+     * - `'stored'`: the user's stored choice wins, and an explicit default only
+     *   applies to columns with no stored value. Only the columns the user
+     *   changed away from their default are stored, so a column the user never
+     *   touched follows a default you change later.
+     *
+     * New tables should choose `'stored'`. Switching an existing table is safe:
+     * the stored value keeps its shape, and entries written under `'defaults'`
+     * are then read as the user's choices.
+     */
+    columnVisibilityPrecedence?: 'defaults' | 'stored';
+    /**
+     * Starting state for an uncontrolled table, applied once on mount. A
+     * controlled `sorting`, `columnVisibility` or `rowSelection` prop wins over
+     * the matching key.
      */
     initialState?: {
         /** Initial sort order. */
         sorting?: SortingState;
         /** Initially selected rows, keyed by row id. */
         rowSelection?: RowSelectionState;
-        /** Initially hidden or shown columns. */
+        /**
+         * Initially hidden or shown columns. With `storageKey`,
+         * `columnVisibilityPrecedence` decides whether these values or the
+         * stored ones win for the same column.
+         */
         columnVisibility?: VisibilityState;
         /** Initial column filters. */
         columnFilters?: ColumnFiltersState;
-        /** Initial page position and size. */
-        pagination?: {
-            pageIndex: number;
-            pageSize: number;
-        };
     };
     /**
      * Storage key for persisting table state (column visibility, etc.) to localStorage.
@@ -440,10 +478,14 @@ export interface DataTableProps<TData extends object, TValue> {
      * Internally formatted as: `dt.{storageKey}.columns`
      *
      * When enabled, the DataTable will:
-     * - Load initial column visibility from localStorage
+     * - Apply stored column visibility after mount, before the first paint.
+     *   The first render uses the explicit defaults, so server markup hydrates
+     *   without a mismatch
+     * - Keep `initialState.columnVisibility` entries ahead of stored values for
+     *   the same column, unless
+     *   `columnVisibilityPrecedence="stored"` puts the user's choice first
      * - Automatically save changes to localStorage
-     * - Handle SSR safely (no errors on server)
-     * - Gracefully handle quota exceeded errors
+     * - Gracefully handle unreadable stored state and quota exceeded errors
      *
      * @example
      * <DataTable
@@ -461,8 +503,6 @@ export interface DataTableFilterBarProps<TData> {
     table: Table<TData>;
     /** Column id the filter input searches. */
     filterColumn?: string;
-    /** Placeholder for the filter input. */
-    filterPlaceholder?: string;
     /** Renders the column-visibility control. */
     enableColumnVisibility?: boolean;
     /** Extra controls rendered in the filter bar. */
@@ -485,13 +525,15 @@ export interface DataTableActionsProps<TData> {
     strings?: DataTableStrings;
 }
 export interface DataTableBodyProps<TData> {
+    /** Replaces the body with non-interactive shared Skeleton rows. */
+    loading?: boolean;
+    /** Number of placeholder rows. Defaults to 6, capped at 20. */
+    loadingRows?: number;
     /** The table instance from `useReactTable`, supplied by `DataTable`. */
     table: Table<TData>;
     /** Fired when a row is activated. */
     onRowClick?: RowClickHandler<TData>;
-    /** Copy shown when there are no rows. */
-    emptyStateMessage?: string;
-    /** Control offered alongside the empty message. */
+    /** Control offered alongside the empty message (`strings.emptyState.message`). */
     emptyStateAction?: React.ReactNode;
     /** Merged onto the cell. */
     cellClassName?: string | ((column: string, row: Row<TData> | null) => string);
@@ -511,11 +553,11 @@ export interface DataTableHeaderProps<TData> {
     enableResizing?: boolean;
     /** Pins the header row while the body scrolls. */
     stickyHeader?: boolean;
-    /** Merged onto the header. */
-    headerClassName?: string;
+    /** Merged onto the header's outermost node. */
+    className?: string;
     /** Merged onto the cell. */
     cellClassName?: string | ((column: string, row: Row<TData> | null) => string);
-    /** Pins the first column while the table scrolls horizontally. */
+    /** Pins the first data column, and the checkbox column before it, while the table scrolls horizontally. */
     stickyFirstColumn?: boolean;
     /** Banded headers spanning several columns, drawn above the header row. */
     columnGroups?: ColumnGroup[];

package/dist/components/features/theme-tweaker/theme-provider-settings.d.ts

@@ -44,6 +44,10 @@ export interface ThemeProviderSettingsStrings {
     };
     dualPricingDescription: string;
     displayCurrencyPlaceholder: string;
+    /** Field error while the locale is not one the runtime can format with. */
+    invalidLocale?: string;
+    /** Field error while a currency is not a three-letter code. */
+    invalidCurrency?: string;
     options: Record<string, string>;
 }
 export declare const defaultThemeProviderSettingsStrings: ThemeProviderSettingsStrings;

package/dist/components/features/theme-tweaker/theme-tweaker.strings.d.ts

@@ -12,8 +12,6 @@ export interface ThemeTweakerStrings {
     groupNavigationLabel: string;
     previousGroup: string;
     nextGroup: string;
-    groupNavigationTitle: string;
-    groupNavigationDescription: string;
     sharedScope: string;
     mixedScope: string;
     variableCount: string;
@@ -23,9 +21,6 @@ export interface ThemeTweakerStrings {
     reset: string;
     copy: string;
     copyProvider: string;
-    copyOverrides: string;
-    exportProvider: string;
-    exportOptions: string;
     export: string;
     exportPending: string;
     exportDialogTitle: string;
@@ -36,6 +31,16 @@ export interface ThemeTweakerStrings {
     copiedStatus: string;
     exportedStatus: string;
     invalidTheme: string;
+    /** Shown in the export dialog when copying fails. Defaults to "Could not copy. Select the text and copy it manually." */
+    copyFailedStatus?: string;
+    /** Shown in the export dialog when a download or `onExport` fails. Defaults to "Could not download the file. Try again." */
+    exportFailedStatus?: string;
+    /** Message of the error reported through `onError` when no clipboard exists and no `onCopy` is supplied. */
+    clipboardUnavailable?: string;
+    /** Field error for a value that could break out of its CSS declaration. */
+    invalidValue?: string;
+    /** Field error for a color field whose value the browser does not read as a color. */
+    invalidColor?: string;
     emptySearch: string;
     inheritValue: string;
     resetVariable: string;
@@ -44,8 +49,6 @@ export interface ThemeTweakerStrings {
     changedCount: string;
     cssOutputLabel: string;
     cssOutputDescription: string;
-    overrideOutputLabel: string;
-    overrideOutputDescription: string;
     providerOutputLabel: string;
     providerOutputDescription: string;
     autoPalette: string;

package/dist/components/features/theme-tweaker/theme-tweaker.utils.d.ts

@@ -1,8 +1,25 @@
 import { type UIConfig } from '../../../lib/ui-provider';
 import type { AdminUIThemeDefinition, AdminUIThemeMode, AdminUIThemeOverrides, AdminUIThemeSelectors, AdminUIThemeStyle, AdminUIThemeVariableName, CreateThemeTweakerExportArtifactOptions, SerializeAdminUIThemeOptions, ThemeTweakerExportArtifact } from './theme-tweaker.types';
 export declare const defaultAdminUIThemeSelectors: AdminUIThemeSelectors;
+/**
+ * Whether a value could break out of its `--name: value;` declaration. This is
+ * the check `serializeAdminUITheme` enforces; the editor uses it to mark the
+ * field that holds the value.
+ */
+export declare function isUnsafeAdminUIThemeValue(rawValue: string): boolean;
+/**
+ * Whether the browser parses a value as a color. `var()` references count,
+ * and so does every value where the browser cannot be asked.
+ */
+export declare function isAdminUIThemeColorValue(rawValue: string): boolean;
 export declare function createAdminUITheme(value?: Partial<AdminUIThemeDefinition>): AdminUIThemeDefinition;
 export declare function isAdminUIThemeVariableName(value: string): value is AdminUIThemeVariableName;
+/**
+ * Serializes theme overrides as CSS text. Values and selectors that could leave
+ * their declaration or rule throw, so validate tenant input at this boundary.
+ * The text is safe as a stylesheet file or through `textContent`; never insert
+ * it with `innerHTML` or `dangerouslySetInnerHTML`.
+ */
 export declare function serializeAdminUITheme(theme: AdminUIThemeDefinition, options?: SerializeAdminUIThemeOptions): string;
 /**
  * Returns the complete serializable UIProvider contract. Function and

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

@@ -5,6 +5,14 @@ export type TopbarSidebarContentElement = 'main' | 'div';
 export type TopbarSidebarMobileSidebarMode = 'drawer' | 'inline';
 export type AppShellContentSurface = 'plain' | 'inset';
 export type AppShellSidebarPresentation = 'panel' | 'rail';
+export interface AppShellSkipLinkProps {
+    /**
+     * Renders a skip link as the shell's first tab stop, with this label. It
+     * appears on keyboard focus and moves focus to the page viewport, past the
+     * header and navigation. Omitted, the shell renders none.
+     */
+    skipToContentLabel?: string;
+}
 export interface AppShellSidebarRegionProps {
     /** Width of contextual navigation; defaults to the shared sidebar width. */
     secondarySidebarWidth?: string;
@@ -18,32 +26,28 @@ export interface AppShellSidebarRegionProps {
 export interface TopbarSidebarLayoutSlots {
     /** Full header replacement inside the themed header region. */
     header?: ReactNode;
-    /** Sidebar trigger rendered before the logo, usually visible on mobile. */
-    sidebarTrigger?: ReactNode;
-    /** Brand/logo block rendered at the far left of the header. */
-    logo?: ReactNode;
     /** Content rendered after the logo and before the center slot. */
     headerStart?: ReactNode;
-    /** Header center region, usually search or a scope switcher. */
+    /**
+     * Header center region, usually search or a scope switcher. It is hidden
+     * while the shell is narrower than 48rem (the `3xl/app-shell` container
+     * width), on phones and in narrow embeds alike. Keep an essential entry
+     * point reachable there through `headerStart`, `headerActions` or
+     * `headerEnd`, for example an icon-only search trigger.
+     */
     headerCenter?: ReactNode;
-    /** Header actions rendered before the trailing account/notification region. */
-    headerActions?: ReactNode;
     /** Header trailing region, usually notifications/user/actions. */
     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;
 }
 export type TopbarSidebarLayoutStyle = CSSProperties & {
     '--shell-header-height'?: string;
     '--shell-sidebar-width'?: string;
 };
-export interface TopbarSidebarLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps {
+export interface TopbarSidebarLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps, AppShellSkipLinkProps {
     /** Page content rendered in the content column. */
     children?: ReactNode;
     /** 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. */
@@ -54,21 +58,17 @@ export interface TopbarSidebarLayoutProps extends Omit<HTMLAttributes<HTMLDivEle
     sidebarSide?: TopbarSidebarSide;
     /** `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 4rem. */
-    headerHeight?: string;
-    /** Expanded sidebar column width CSS value. Defaults to `var(--shell-sidebar-width)`, whose root default is 16rem. */
-    sidebarWidth?: string;
-    /** Convenience mobile/sidebar trigger slot. Prefer `slots.sidebarTrigger` when composing many regions. */
+    /** Sidebar trigger rendered before the logo, usually visible on mobile. */
     sidebarTrigger?: ReactNode;
-    /** Convenience logo slot. Prefer `slots.logo` when composing many regions. */
+    /** Brand/logo block rendered at the far left of the header. */
     logo?: ReactNode;
-    /** Convenience header actions slot. Prefer `slots.headerActions` when composing many regions. */
+    /** Header actions rendered before the trailing account/notification region. */
     headerActions?: ReactNode;
-    /** Convenience sidebar slot. Prefer `slots.sidebar` when composing many regions. */
+    /** Sidebar column content. */
     sidebar?: ReactNode;
-    /** Named content regions. */
+    /** The remaining header regions, the contextual sidebar and the supporting panel. */
     slots?: TopbarSidebarLayoutSlots;
-    /** Semantic element for the content column. */
+    /** Semantic element for the content column. Defaults to `main`, or to `div` when the shell is embedded in an existing main landmark. */
     contentAs?: TopbarSidebarContentElement;
     /** Merged onto the header region. */
     headerClassName?: string;
@@ -86,24 +86,18 @@ export type SidebarInsetContentElement = 'main' | 'div';
 /** `inset` floats the content on the sidebar surface; `flush` sits it edge to edge. */
 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. */
-    sidebarTrigger?: ReactNode;
     /** Leading toolbar region, usually a breadcrumb or page title. */
     toolbarStart?: ReactNode;
     /** Trailing toolbar region, usually actions or an account menu. */
     toolbarEnd?: ReactNode;
-    /** Full content replacement; falls back to `children`. */
-    content?: ReactNode;
 }
-export interface SidebarInsetLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps {
+export interface SidebarInsetLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSidebarRegionProps, AppShellSkipLinkProps {
     /** Page content rendered in the content column. */
     children?: ReactNode;
     /** Sidebar side. */
@@ -114,15 +108,13 @@ export interface SidebarInsetLayoutProps extends Omit<HTMLAttributes<HTMLDivElem
     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. */
-    sidebarWidth?: string;
-    /** Convenience sidebar slot. */
+    /** Sidebar column content, spanning the full page height. */
     sidebar?: ReactNode;
-    /** Convenience trigger slot. */
+    /** Sidebar trigger, rendered at the start of the toolbar. */
     sidebarTrigger?: ReactNode;
-    /** Named content regions. */
+    /** The toolbar regions, the contextual sidebar and the supporting panel. */
     slots?: SidebarInsetLayoutSlots;
-    /** Semantic element for the content region. */
+    /** Semantic element for the content region. Defaults to `main`, or to `div` when the shell is embedded in an existing main landmark. */
     contentAs?: SidebarInsetContentElement;
     /** Merged onto the sidebar region. */
     sidebarClassName?: string;
@@ -137,38 +129,43 @@ export type StackedContentWidth = 'contained' | 'full';
 export interface StackedLayoutSlots {
     /** Full header replacement. */
     header?: ReactNode;
-    /** Brand/logo block at the start of the header. */
-    logo?: ReactNode;
-    /** Primary horizontal navigation, rendered after the logo. */
-    nav?: ReactNode;
     /** Trailing header region, usually search, notifications or an account menu. */
     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'> {
+export type StackedNavElement = 'nav' | 'div';
+export interface StackedLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AppShellSkipLinkProps {
     /** Page content. */
     children?: ReactNode;
     /** 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. */
+    /**
+     * Constrains the content to the shell's reading width, or lets it span.
+     * The contained measure owns the inline page gutter, so a `Page` inside it
+     * defaults to no gutter of its own; an explicit `gutter` on the Page wins.
+     */
     contentWidth?: StackedContentWidth;
-    /** Header height CSS value. */
-    headerHeight?: string;
     /** Width of the optional supporting panel. */
     asideWidth?: string;
     asideClassName?: string;
-    /** Convenience logo slot. */
+    /** Brand/logo block at the start of the header. */
     logo?: ReactNode;
-    /** Convenience navigation slot. */
+    /** Primary horizontal navigation, rendered after the logo. */
     nav?: ReactNode;
-    /** Named content regions. */
+    /** Accessible name of the navigation landmark. @default 'Primary navigation' */
+    navLabel?: string;
+    /**
+     * Element of the navigation region. Use `div` when the slot content renders
+     * its own `nav` landmark (NavigationTabs, for example), so landmarks do not nest.
+     * @default 'nav'
+     */
+    navAs?: StackedNavElement;
+    /** The header replacement, its trailing region, the subheader and the supporting panel. */
     slots?: StackedLayoutSlots;
-    /** Semantic element for the content region. */
+    /** Semantic element for the content region. Defaults to `main`, or to `div` when the shell is embedded in an existing main landmark. */
     contentAs?: StackedContentElement;
     /** Merged onto the header region. */
     headerClassName?: string;

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

@@ -1,6 +1,6 @@
 export { TopbarSidebarLayout } from './topbar-sidebar-layout';
-export type { AppShellContentSurface, AppShellSidebarPresentation, AppShellSidebarRegionProps, TopbarSidebarContentElement, TopbarSidebarHeaderTheme, TopbarSidebarLayoutProps, TopbarSidebarLayoutSlots, TopbarSidebarLayoutStyle, TopbarSidebarSide, } from './app-shell.types';
+export type { AppShellContentSurface, AppShellSidebarPresentation, AppShellSidebarRegionProps, AppShellSkipLinkProps, 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';
+export type { SidebarInsetContentElement, SidebarInsetLayoutProps, SidebarInsetLayoutSlots, SidebarInsetSide, SidebarInsetSurface, StackedContentElement, StackedContentWidth, StackedLayoutProps, StackedLayoutSlots, StackedNavElement, } from './app-shell.types';
 export { AppLayout, type AppLayoutProps, type AppLayoutVariant } from './app-layout';

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

@@ -24,4 +24,13 @@ interface ShellRegionGridProps {
 }
 /** 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;
+/**
+ * Reserves the page viewport's scrollbar gutter in a row above it. The viewport
+ * keeps a stable gutter, so with classic scrollbars its content box ends that
+ * much before its edge. This empty element reserves the same gutter, so it is
+ * exactly one scrollbar wide (zero with overlay scrollbars) and a header beside
+ * it ends where the page does. It clips rather than scrolls: the page viewport
+ * stays the shell's only scroller.
+ */
+export declare function ShellScrollbarSpacer(): import("react").JSX.Element;
 export {};

package/dist/components/layout/app-shell/shell-skip-link.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The first tab stop of a shell: jumps over the header and navigation to the
+ * page viewport. It stays out of sight until it takes keyboard focus, and it
+ * moves focus without rewriting the URL hash, so hash routes survive.
+ */
+export declare function ShellSkipLink({ targetId, label }: {
+    targetId: string;
+    label: string;
+}): import("react").JSX.Element;

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, mobileSidebarMode, toolbar, sidebarWidth, secondarySidebarWidth, asideWidth, sidebarPresentation, secondarySidebarClassName, asideClassName, 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, secondarySidebarWidth, asideWidth, sidebarPresentation, secondarySidebarClassName, asideClassName, sidebar, sidebarTrigger, slots, contentAs, skipToContentLabel, 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, asideWidth, asideClassName, logo, nav, slots, contentAs: Content, className, headerClassName, subheaderClassName, contentClassName, style, ...props }: StackedLayoutProps): import("react").JSX.Element;
+export declare function StackedLayout({ children, headerTheme, contentWidth, asideWidth, asideClassName, logo, nav, navLabel, navAs: Nav, slots, contentAs, skipToContentLabel, 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, 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;
+export declare function TopbarSidebarLayout({ children, headerTheme, contentSurface, sidebarSide, mobileSidebarMode, secondarySidebarWidth, asideWidth, sidebarPresentation, secondarySidebarClassName, asideClassName, sidebarTrigger, logo, headerActions, sidebar, slots, contentAs, skipToContentLabel, className, headerClassName, headerInnerClassName, bodyClassName, sidebarClassName, contentClassName, style, ...props }: TopbarSidebarLayoutProps): import("react").JSX.Element;

package/dist/components/layout/auth/auth-shell.d.ts

@@ -1,2 +1,2 @@
 import type { AuthShellProps } from './auth.types';
-export declare function AuthShell({ children, variant: variantProp, size, align, brand, eyebrow, title, description, headerEnd, banner, cardMedia, cardMediaClassName, cardFooter, postCard, footer, footerLinks, policyLinks, languageLinks, languageSwitcher, socialProviders, socialProvidersLayout, socialDivider, splitPanel, splitSide, splitMobile, renderLink, className, mainClassName, stackClassName, cardClassName, cardContentClassName, splitGridClassName, splitPanelClassName, footerClassName, strings: stringsProp, ...props }: AuthShellProps): import("react").JSX.Element;
+export declare function AuthShell({ children, variant: variantProp, size, align, brand, eyebrow, title, description, headerEnd, banner, cardMedia, cardMediaClassName, cardFooter, postCard, footer, footerLinks, policyLinks, languageLinks, languageSwitcher, socialProviders, socialProvidersLayout, splitPanel, splitSide, splitMobile, renderLink, className, mainClassName, stackClassName, splitGridClassName, splitPanelClassName, strings: stringsProp, ...props }: AuthShellProps): import("react").JSX.Element;