themelia-react-ui 2.0.6 → 3.0.0

package/dist/components/features/table/table-body.d.ts

@@ -1,5 +1,5 @@
 import { type DataTableBodyProps } from './table.types';
-export declare function DataTableBody<TData>({ loading, loadingRows, table, onRowClick, emptyStateMessage, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, striped, strings, }: DataTableBodyProps<TData>): import("react").JSX.Element;
+export declare function DataTableBody<TData>({ loading, loadingRows, table, onRowClick, emptyStateAction, cellClassName, rowClassName, stickyFirstColumn, striped, strings, }: DataTableBodyProps<TData>): import("react").JSX.Element;
 export declare namespace DataTableBody {
     var displayName: string;
 }

package/dist/components/features/table/table-header.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { type DataTableHeaderProps } from './table.types';
-export declare function DataTableHeader<TData>({ table, enableResizing, stickyHeader, headerClassName, cellClassName, stickyFirstColumn, columnGroups, headerTransparent, strings, }: DataTableHeaderProps<TData>): React.JSX.Element;
+export declare function DataTableHeader<TData>({ table, enableResizing, stickyHeader, className, cellClassName, stickyFirstColumn, columnGroups, headerTransparent, strings, }: DataTableHeaderProps<TData>): React.JSX.Element;
 export declare namespace DataTableHeader {
     var displayName: string;
 }

package/dist/components/features/table/table-helpers.d.ts

@@ -7,21 +7,41 @@ export interface GeneratedColumnOptions<TData> {
 }
 export declare function getGeneratedColumnOptions<TData>(table: Table<TData>): GeneratedColumnOptions<TData> | undefined;
 /**
- * Helper function for handling row selection changes with OnChangeFn compatibility
+ * Helper function for handling row selection changes with OnChangeFn compatibility.
+ * Pass the current selection as `currentState` to resolve updater functions
+ * outside React's state updater.
  */
-export declare const handleRowSelectionChange: (updatedSelection: Updater<RowSelectionState>, setInternalState: React.Dispatch<React.SetStateAction<RowSelectionState>>, externalHandler?: (state: RowSelectionState) => void) => void;
+export declare const handleRowSelectionChange: (updatedSelection: Updater<RowSelectionState>, setInternalState: React.Dispatch<React.SetStateAction<RowSelectionState>>, externalHandler?: (state: RowSelectionState) => void, currentState?: RowSelectionState) => void;
 /**
- * Helper function for handling sorting changes with OnChangeFn compatibility
+ * Helper function for handling sorting changes with OnChangeFn compatibility.
+ * Pass the current sorting as `currentState` to resolve updater functions
+ * outside React's state updater.
  */
-export declare const handleSortingChange: (updatedSorting: Updater<SortingState>, setInternalState: React.Dispatch<React.SetStateAction<SortingState>>, externalHandler?: (state: SortingState) => void) => void;
+export declare const handleSortingChange: (updatedSorting: Updater<SortingState>, setInternalState: React.Dispatch<React.SetStateAction<SortingState>>, externalHandler?: (state: SortingState) => void, currentState?: SortingState) => void;
 /**
- * Helper function for handling column visibility changes
+ * Helper function for handling column visibility changes. Pass the current
+ * visibility as `currentState` to resolve updater functions outside React's
+ * state updater.
  */
-export declare const handleColumnVisibilityChange: (updatedVisibility: Updater<VisibilityState>, setInternalState: React.Dispatch<React.SetStateAction<VisibilityState>>, externalHandler?: (state: VisibilityState) => void) => void;
+export declare const handleColumnVisibilityChange: (updatedVisibility: Updater<VisibilityState>, setInternalState: React.Dispatch<React.SetStateAction<VisibilityState>>, externalHandler?: (state: VisibilityState) => void, currentState?: VisibilityState) => void;
 /**
  * Get row class name based on selection state and custom function
  */
 export declare const getRowClassName: <TData>(row: Row<TData>, index: number, rowClassName?: string | ((row: Row<TData>, index: number) => string), isSelected?: boolean) => string;
+/** Which pinned role a column plays when `stickyFirstColumn` is on. */
+export type PinnedColumnRole = 'selection' | 'first';
+/**
+ * The pinned role of the column at `index`, given the visible leaf column ids
+ * in order. The checkbox column and the first data column pin as a pair, so a
+ * selectable table keeps its identifying column in view.
+ */
+export declare function getPinnedColumnRole(columnIds: readonly string[], index: number, stickyFirstColumn?: boolean): PinnedColumnRole | undefined;
+/**
+ * Classes for a pinned cell. The data column sits after the checkbox column
+ * by `--data-table-selection-width`, which DataTable sets on the table area;
+ * only the last pinned column draws the trailing edge.
+ */
+export declare function getPinnedCellClassName(role: PinnedColumnRole | undefined, afterSelection: boolean): string;
 /**
  * Get cell class name including sticky column handling
  */
@@ -31,11 +51,13 @@ export declare const getCellClassName: <TData>(columnId: string, row: Row<TData>
  */
 export declare const getSelectedRowsData: <T extends object>(table: Table<T>) => T[];
 /**
- * Create row selection component for a row
+ * Create row selection component for a row. With `table`, the checkbox is
+ * named by the row's position on screen rather than its index in `data`.
  */
-export declare const createRowSelectionCheckbox: <TData>(row: Row<TData>, strings?: DataTableStrings) => React.JSX.Element;
+export declare const createRowSelectionCheckbox: <TData>(row: Row<TData>, strings?: DataTableStrings, table?: Table<TData>) => React.JSX.Element;
 /**
- * Create header selection checkbox
+ * Create header selection checkbox. A table that allows one selected row has
+ * nothing to select all of, so its header only names the column.
  */
 export declare const createHeaderSelectionCheckbox: <TData>(table: Table<TData>, strings?: DataTableStrings) => React.JSX.Element;
 /** Prepends the checkbox selection column. Explicit strings override table defaults. */

package/dist/components/features/table/table-region.recipes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Inline inset for every region that sits above or below a table inside the
+ * same frame: topbar, toolbar, filter bar, selection bar, footer, pagination.
+ *
+ * It is the edge of the table's outer cells, as `base/table/table.css` draws
+ * it: the surface inset (`--surface-x` × `--space-scale`, 24px by default),
+ * and flush inside a padded Card body, where the card already owns the inset.
+ * Sharing the rule keeps a region's text on the first column's edge under any
+ * scoped spacing, and in a flat table composed into a Card.
+ */
+export declare const tableRegionInsetClassName = "px-surface [.card--content:not([data-padding=none])_&:not(.card--content[data-padding=none]_*)]:px-0";

package/dist/components/features/table/table-toolbar.d.ts

@@ -1,5 +1,5 @@
 import { type DataTableToolbarProps } from './table.types';
-export declare function DataTableToolbar<TData>({ table, tableAreaRef, fullscreen, onFullscreenChange, showFullscreenToggle, enableColumnVisibility, labelVisibility, strings, }: DataTableToolbarProps<TData>): import("react").JSX.Element | null;
+export declare function DataTableToolbar<TData>({ table, tableAreaRef, fullscreen, onFullscreenChange, showFullscreenToggle, enableColumnVisibility, labelVisibility, strings, className, }: DataTableToolbarProps<TData>): import("react").JSX.Element | null;
 export declare namespace DataTableToolbar {
     var displayName: string;
 }

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

@@ -46,6 +46,7 @@ export declare const defaultDataTableStrings: {
         summary: (selected: number, total: number) => string;
         row: (index: number) => string;
         selectAll: string;
+        columnLabel: string;
         clear: string;
         label: string;
     };

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 */
@@ -113,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;
@@ -173,6 +189,8 @@ 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>;
@@ -251,18 +269,12 @@ export interface DataTableProps<TData extends object, TValue> {
     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. */
@@ -273,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;
@@ -298,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;
@@ -318,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. */
@@ -376,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. */
@@ -420,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.
@@ -452,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
@@ -473,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. */
@@ -505,9 +533,7 @@ export interface DataTableBodyProps<TData> {
     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);
@@ -527,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;