@nice2dev/ui 1.0.18 → 1.0.20

package/dist/index.d.ts

@@ -63,6 +63,7 @@ import { createUserPreferencesStore } from '@nice2dev/ui-core';
 import { createWebSocketDataSource } from '@nice2dev/ui-core';
 import { createZustandAdapter } from '@nice2dev/ui-core';
 import { CrossTabMessage } from '@nice2dev/ui-core';
+import { CSSProperties } from 'react';
 import { default as default_2 } from 'react';
 import { DEFAULT_VARIANT_CONFIG } from '@nice2dev/ui-core';
 import { DENSITY_VALUES } from '@nice2dev/ui-core';
@@ -1766,6 +1767,20 @@ export { buildFormFieldAria }
 /** Build the iCalendar text body for the given events. */
 export declare function buildIcs(events: NiceIcsEvent[], options?: ExportIcsOptions): string;
 
+/** Build resolved `SidebarNavView` items with translated labels. */
+export declare function buildPrefsCategoryViews(t: (key: string, defaultValue: string) => string): SidebarNavView[];
+
+/**
+ * Returns a `Record<route, ReactNode>` of the built-in sidebar preference
+ * routes (`preferences/general`, `preferences/display`, `preferences/order`,
+ * `preferences/hidden`, `preferences/reset`) — ready to be merged into
+ * `NiceNavShell`'s `routes` prop.
+ *
+ * NavShell auto-merges these when `includeSidebarPreferenceRoutes` is left at
+ * its default `true`. Call this manually when you want fine-grained control.
+ */
+export declare function buildSidebarPrefsRoutes(): Record<string, ReactNode>;
+
 /** Bulk operation */
 export declare interface BulkOperation {
     id: string;
@@ -9035,6 +9050,29 @@ export declare interface NiceColorPaletteProps extends NiceBaseProps {
     label?: string;
     /** Disabled state */
     disabled?: boolean;
+    /**
+     * Target number of colors in the generated palette. Overrides the natural
+     * count of the active harmony mode (clamped between `minColors` and
+     * `maxColors`). When omitted, the harmony's natural angle count is used.
+     */
+    colorCount?: number;
+    /**
+     * Step size (HSV value delta) between adjacent colors in the `shade-chain`
+     * mode. Default 0.12.
+     */
+    shadeStep?: number;
+    /** Called when the user changes the shade step via the in-component control. */
+    onShadeStepChange?: (step: number) => void;
+    /**
+     * Custom harmony schemes. Appended to the built-in mode list in the
+     * selector and persisted via `localStorage` when `persistCustomSchemes`
+     * is true.
+     */
+    customSchemes?: NiceCustomHarmonyScheme[];
+    /** Called when the user edits the custom-schemes list. */
+    onCustomSchemesChange?: (schemes: NiceCustomHarmonyScheme[]) => void;
+    /** Persist custom schemes to `localStorage["nice-palette-custom-schemes"]`. Default true. */
+    persistCustomSchemes?: boolean;
 }
 
 export declare const NiceColorPicker: default_2.ForwardRefExoticComponent<NiceColorPickerProps & default_2.RefAttributes<HTMLInputElement>>;
@@ -9936,6 +9974,12 @@ export declare interface NiceCountryPickerProps extends NiceFormFieldProps, Dual
      * false (except flag) and ignoring `controlWidth`. Default: false.
      */
     compact?: boolean;
+    /**
+     * Visual variant. `'ghost'` removes border, background and the dropdown
+     * arrow — only the flag/icon is shown. Designed for dense toolbars
+     * (e.g. NiceTopNav narrow mode). Default: `'default'`.
+     */
+    variant?: 'default' | 'ghost';
     /**
      * Dropdown horizontal alignment relative to the trigger. `'auto'` picks
      * the side with more available viewport space (right-edge preferred).
@@ -10105,6 +10149,15 @@ export { NiceCursorPaginationConfig }
 
 export { NiceCustomDataSourceHandlers }
 
+/** A user-defined harmony scheme (hue angles + optional lightness offsets). */
+declare interface NiceCustomHarmonyScheme {
+    id: string;
+    name: string;
+    angles: number[];
+    /** Optional per-color lightness deltas applied on top of preset/base V. */
+    lightnessOffsets?: number[];
+}
+
 export declare const NiceDashboardLayout: default_2.ForwardRefExoticComponent<NiceDashboardLayoutProps & default_2.RefAttributes<HTMLDivElement>>;
 
 /** Props for the {@link NiceDashboardLayout} component — a CSS-grid dashboard with draggable, resizable panels. */
@@ -10838,6 +10891,8 @@ export declare interface NiceDisplayStylePickerProps extends NiceBaseProps {
     label?: string;
     /** Filter to show only specific styles. */
     styles?: NiceDisplayStyle[];
+    /** Compact mode — forces dropdown layout for tight spaces. */
+    compact?: boolean;
 }
 
 export declare const NiceDivider: default_2.FC<NiceDividerProps>;
@@ -12815,7 +12870,7 @@ export declare interface NiceGradientValue {
 
 export { NiceGraphQLConfig }
 
-export declare type NiceHarmonyMode = 'monochromatic' | 'complementary' | 'split-complementary' | 'analogous' | 'triadic' | 'tetradic' | 'square' | 'custom';
+export declare type NiceHarmonyMode = 'monochromatic' | 'complementary' | 'split-complementary' | 'analogous' | 'triadic' | 'tetradic' | 'square' | 'shade-chain' | 'custom';
 
 /**
  * Semantic heading with decoupled visual scale. Renders the correct
@@ -13704,6 +13759,12 @@ export declare interface NiceLanguagePickerProps extends NiceFormFieldProps, Dua
      * dropdown alignment. Default: false.
      */
     compact?: boolean;
+    /**
+     * Visual variant. `'ghost'` removes border, background and the dropdown
+     * arrow — only the flag is shown. Designed for dense toolbars
+     * (e.g. NiceTopNav narrow mode). Default: `'default'`.
+     */
+    variant?: 'default' | 'ghost';
     /**
      * Dropdown horizontal alignment relative to trigger. `'auto'` picks the
      * side with more available viewport space. Default: `'auto'` in compact
@@ -14944,6 +15005,12 @@ export declare interface NiceMenuProps extends NiceBaseProps {
     renderTriggerLabel?: (item: NiceMenuItem) => default_2.ReactNode;
     /** Optional renderer for panel-entry label. */
     renderEntryLabel?: (item: NiceMenuItem) => default_2.ReactNode;
+    /**
+     * Maximum depth of nested flyouts rendered. `1` = top-level only, `2` = level-1 panel,
+     * `3` = level-2 subpanel (default — preserves legacy behavior), up to `10`. Items with
+     * `children` beyond this depth are rendered as leaves (no flyout arrow, no hover-open).
+     */
+    maxDepth?: number;
 }
 
 /**
@@ -15615,7 +15682,14 @@ export declare const NiceNavShell: ForwardRefExoticComponent<NiceNavShellProps &
 export declare interface NiceNavShellApi {
     activeRoute: string | undefined;
     tabs: NiceNavShellTab[];
-    openRoute: (route: string, opts?: Partial<NiceNavShellTab>) => void;
+    /** True when the shell is in narrow/mobile layout (viewport ≤ `mobileBreakpoint`
+     *  or `forceMobileLayout`). Render-prop slot consumers should forward this to
+     *  any embedded `NiceTopNav` (`forceMobileLayout={isMobile}`) so the hamburger
+     *  switch happens at the same width the sidebar disappears. */
+    isMobile: boolean;
+    openRoute: (route: string, opts?: Partial<NiceNavShellTab> & {
+        forceNew?: boolean;
+    }) => void;
     closeTab: (id: string) => void;
     closeOthers: (id: string) => void;
     closeAll: () => void;
@@ -15623,6 +15697,59 @@ export declare interface NiceNavShellApi {
     setDirty: (id: string, dirty?: boolean) => void;
 }
 
+export declare function NiceNavShellHome({ userName, userId, openTabs, routes, routeLabels, routeIcons, shortcuts, onNavigate, showGreeting, showOpenTabs, showShortcuts, showRoutes, maxItemsPerSection, header, footer, className, style, }: NiceNavShellHomeProps): default_2.ReactElement;
+
+export declare namespace NiceNavShellHome {
+    var displayName: string;
+}
+
+/** Props for {@link NiceNavShellHome} — default `homeContent` rendered by NiceNavShell. */
+export declare interface NiceNavShellHomeProps {
+    /** Display name used in the greeting. */
+    userName?: string;
+    /** User id used to derive shortcuts from NiceSidebarNav's localStorage prefs when `shortcuts` is omitted. */
+    userId?: string;
+    /** Currently open tabs (typically NavShell's `tabs` minus the home tab). */
+    openTabs?: NiceNavShellTab[];
+    /** Map of all available routes (just the keys are read). */
+    routes?: Record<string, unknown>;
+    /** Per-route label overrides. */
+    routeLabels?: Record<string, ReactNode>;
+    /** Per-route icon overrides. */
+    routeIcons?: Record<string, ReactNode>;
+    /** Explicit shortcut list. When set, suppresses auto-derived sidebar favorites. */
+    shortcuts?: NiceNavShellHomeShortcut[];
+    /** Called when a tile is clicked. Receives the route key. */
+    onNavigate?: (route: string) => void;
+    /** Default `true`. */
+    showGreeting?: boolean;
+    /** Default `true`. */
+    showOpenTabs?: boolean;
+    /** Default `true`. */
+    showShortcuts?: boolean;
+    /** Default `true`. */
+    showRoutes?: boolean;
+    /** Cap per section. Default `12`. */
+    maxItemsPerSection?: number;
+    /** Custom header content (replaces the greeting block). */
+    header?: ReactNode;
+    /** Custom footer content (e.g. announcement banner). */
+    footer?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+
+/** A pinned shortcut tile rendered in the shortcuts section. */
+export declare interface NiceNavShellHomeShortcut {
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    /** Route to navigate to when clicked. Ignored if `onClick` is given. */
+    route?: string;
+    /** Override the default navigate behaviour. */
+    onClick?: () => void;
+}
+
 export declare type NiceNavShellPersistence = 'memory' | 'localStorage' | 'session';
 
 export declare interface NiceNavShellProps {
@@ -15638,6 +15765,60 @@ export declare interface NiceNavShellProps {
     topNavProps?: NiceTopNavProps;
     /** Sidebar navigation slot. */
     sidebar?: Slot;
+    /**
+     * Shared navigation model. When provided, the shell renders an internal
+     * `NiceSidebarNav` in the sidebar slot (unless an explicit `sidebar` slot
+     * is given) AND forwards the same model to the embedded mobile hamburger
+     * inside `NiceTopNav`. This guarantees one source of truth for both layouts.
+     */
+    sidebarData?: SidebarNavDataNode[];
+    /** User id forwarded to NiceSidebarNav (preferences scope). */
+    sidebarUserId?: string;
+    /** Active route highlighted in the sidebar (defaults to `activeRoute`). */
+    sidebarActiveRoute?: string;
+    /**
+     * Fired when a view is clicked anywhere in the sidebar (desktop or mobile).
+     *
+     * The optional third arg carries the sidebar's `leftClickBehavior` pref
+     * (or `forceNew: true` when the "Open in new tab" context-menu action is
+     * used). NavShell honours it automatically when `autoOpenSidebarRoutes`
+     * is enabled — handlers can ignore it for backward compat.
+     */
+    onSidebarNavigate?: (route: string, view: SidebarNavView, opts?: {
+        forceNew?: boolean;
+    }) => void;
+    /**
+     * When true (default when tabs are enabled), NavShell auto-calls
+     * `openRoute(route, { forceNew })` whenever the sidebar fires
+     * `onNavigate`. Disable to keep the legacy "consumer must wire up
+     * navigation manually" behaviour.
+     */
+    autoOpenSidebarRoutes?: boolean;
+    /**
+     * Resolves a route key to a URL. Forwarded to the auto-rendered
+     * `NiceSidebarNav` so its right-click context menu can show "Open in
+     * new browser tab" and "Copy link".
+     */
+    routeToUrl?: (route: string) => string;
+    /**
+     * Auto-merge the built-in sidebar preference page routes
+     * (`preferences/general`, `/display`, `/order`, `/hidden`, `/reset`) into
+     * `routes`. Defaults to `true` when `sidebarData` is provided. User-defined
+     * routes with matching keys still win.
+     */
+    includeSidebarPreferenceRoutes?: boolean;
+    /**
+     * Viewport breakpoint (px). At or below this width, the desktop sidebar is
+     * hidden and the navigation is delegated to the top-nav hamburger drawer
+     * (which uses the same `sidebarData`). Default `720` — matches
+     * `NiceTopNav`'s own `mobileBreakpoint` so the sidebar disappears at the
+     * exact same width the hamburger appears (no dead zone where neither is
+     * visible). Override on BOTH components together if you need a different
+     * value.
+     */
+    mobileBreakpoint?: number;
+    /** Force the shell into the mobile layout regardless of viewport. */
+    forceMobileLayout?: boolean;
     /** Map of route → content (ReactNode or factory). */
     routes: Record<string, ReactNode | (() => ReactNode)>;
     /** Initial / default route (used when uncontrolled). */
@@ -15686,6 +15867,26 @@ export declare interface NiceNavShellProps {
     initialTabs?: NiceNavShellTab[];
     /** Routes auto-opened as pinned on first mount. */
     pinnedRoutes?: string[];
+    /** Pin a non-closable Home tab as the first tab. Default `true` (when tabs are enabled). */
+    showHomeTab?: boolean;
+    /** Route key for the Home tab. Default `'home'`. */
+    homeRoute?: string;
+    /** Icon rendered in the Home tab. Defaults to a built-in inline house SVG. */
+    homeIcon?: ReactNode;
+    /** Optional label next to the icon. Default `undefined` (icon-only tab). */
+    homeLabel?: ReactNode;
+    /** Content rendered for the Home route. Defaults to a smart `NiceNavShellHome` dashboard. */
+    homeContent?: ReactNode;
+    /** Display name passed to the default Home dashboard greeting. Ignored when `homeContent` is set. */
+    homeUserName?: string;
+    /** Extra props forwarded to the default `NiceNavShellHome` dashboard. Ignored when `homeContent` is set. */
+    homeDashboardProps?: Partial<NiceNavShellHomeProps>;
+    /** Show the built-in `?` button in the embedded top-nav and wire the default help flow. Default `false`. */
+    showHelpButton?: boolean;
+    /** Override default help steps. When omitted, NavShell auto-generates steps from visible elements. */
+    helpSteps?: NiceTutorialStep[];
+    /** Disable individual default steps by key. */
+    helpStepsExclude?: Array<'topNav' | 'sidebar' | 'tabs' | 'content'>;
     className?: string;
     contentClassName?: string;
     'data-testid'?: string;
@@ -15890,6 +16091,12 @@ export declare interface NiceNotificationsProps {
     badgeMax?: number;
     /** Size variant of the trigger. */
     size?: 'sm' | 'md' | 'lg';
+    /**
+     * Visual variant. `'ghost'` removes border, background and hover-border
+     * — only the bell icon (with badge) is shown. Designed for dense toolbars
+     * (e.g. NiceTopNav narrow mode). Default: `'default'`.
+     */
+    variant?: 'default' | 'ghost';
     className?: string;
     style?: default_2.CSSProperties;
     id?: string;
@@ -18898,8 +19105,25 @@ export declare interface NiceSidebarNavProps {
     userId?: string;
     /** Currently active route (for item highlighting) */
     activeRoute?: string;
-    /** Called when user clicks a navigable view */
-    onNavigate?: (route: string, view: SidebarNavView) => void;
+    /**
+     * Called when user clicks a navigable view.
+     *
+     * `opts.forceNew` mirrors the user's `leftClickBehavior` preference (or the
+     * "Open in new tab" context-menu action). Hosts that don't care about this
+     * — e.g. a single-pane layout — can ignore the third argument; nothing else
+     * changes for them.
+     */
+    onNavigate?: (route: string, view: SidebarNavView, opts?: {
+        forceNew?: boolean;
+    }) => void;
+    /**
+     * Resolves a route key to a URL. When provided, the right-click menu shows
+     * "Open in new browser tab" (via `window.open`) and "Copy link". When
+     * omitted, both items are hidden.
+     */
+    routeToUrl?: (route: string) => string;
+    /** Enable the right-click context menu on view nodes. Default `true`. */
+    contextMenu?: boolean;
     /**
      * Override the initial enableModeIcons flag.
      * Can be toggled later via Preferences.
@@ -18929,6 +19153,14 @@ export declare interface NiceSidebarNavProps {
      * Default `false`.
      */
     minimal?: boolean;
+    /**
+     * **Embedded mode** — render the sidebar inside another container (e.g. a
+     * mobile drawer / hamburger menu). Forces full width, drops the footer with
+     * the collapse-btn (there is nothing to collapse to inside a drawer) and
+     * ignores `collapsed` / `width` / `collapsedWidth`. The mode strip and the
+     * full navigation tree stay intact. Default `false`.
+     */
+    embedded?: boolean;
     /** Optional header slot rendered above the mode strip / tree (e.g. workspace switcher). */
     header?: ReactNode;
     /** Optional footer slot rendered below the standard footer-toggle row. */
@@ -18951,6 +19183,58 @@ export declare interface NiceSidebarNavProps {
     'data-testid'?: string;
 }
 
+export declare function NiceSidebarPrefsDisplay({ userId: userIdProp, }?: NiceSidebarPrefsDisplayProps): default_2.ReactElement;
+
+export declare namespace NiceSidebarPrefsDisplay {
+    var displayName: string;
+}
+
+export declare interface NiceSidebarPrefsDisplayProps {
+    userId?: string;
+}
+
+export declare function NiceSidebarPrefsGeneral({ userId: userIdProp, }?: NiceSidebarPrefsGeneralProps): default_2.ReactElement;
+
+export declare namespace NiceSidebarPrefsGeneral {
+    var displayName: string;
+}
+
+export declare interface NiceSidebarPrefsGeneralProps {
+    /** Explicit override — used when consuming this page outside a NavShell scope. */
+    userId?: string;
+}
+
+export declare function NiceSidebarPrefsHidden({ userId: userIdProp, }?: NiceSidebarPrefsHiddenProps): default_2.ReactElement;
+
+export declare namespace NiceSidebarPrefsHidden {
+    var displayName: string;
+}
+
+export declare interface NiceSidebarPrefsHiddenProps {
+    userId?: string;
+}
+
+export declare function NiceSidebarPrefsOrder({ userId: userIdProp, data: dataProp, }?: NiceSidebarPrefsOrderProps): default_2.ReactElement;
+
+export declare namespace NiceSidebarPrefsOrder {
+    var displayName: string;
+}
+
+export declare interface NiceSidebarPrefsOrderProps {
+    userId?: string;
+    data?: SidebarNavDataNode[];
+}
+
+export declare function NiceSidebarPrefsReset({ userId: userIdProp, }?: NiceSidebarPrefsResetProps): default_2.ReactElement;
+
+export declare namespace NiceSidebarPrefsReset {
+    var displayName: string;
+}
+
+export declare interface NiceSidebarPrefsResetProps {
+    userId?: string;
+}
+
 export { NiceSignalRConfig }
 
 export declare const NiceSignature: default_2.ForwardRefExoticComponent<NiceSignatureProps & default_2.RefAttributes<NiceSignatureRef>>;
@@ -20355,10 +20639,14 @@ export declare interface NiceThemeBuilderProps extends NiceBaseProps {
     livePreview?: boolean;
     /** Currently focused token from NiceThemePreview (auto-switches section + scrolls) */
     focusedToken?: string;
+    /** Show the embedded NiceThemePreview pane (default: true) */
+    showPreview?: boolean;
+    /** Layout placement of the preview pane (default: 'right') */
+    previewPlacement?: 'right' | 'bottom';
 }
 
 /** Editable sections in the {@link NiceThemeBuilder}. */
-export declare type NiceThemeBuilderSection = 'general' | 'colors' | 'backgrounds' | 'background-image' | 'text' | 'borders' | 'spacing' | 'typography' | 'shadows' | 'transitions';
+export declare type NiceThemeBuilderSection = 'general' | 'colors' | 'backgrounds' | 'background-image' | 'text' | 'borders' | 'spacing' | 'typography' | 'shadows' | 'transitions' | 'nesting';
 
 export { NiceThemeColors }
 
@@ -20507,6 +20795,12 @@ export declare interface NiceThemePickerProps extends NiceFormFieldProps, DualVi
      * dropdown alignment. Default: false.
      */
     compact?: boolean;
+    /**
+     * Visual variant. `'ghost'` removes border, background and the dropdown
+     * arrow — only the preview swatch is shown. Designed for dense toolbars
+     * (e.g. NiceTopNav narrow mode). Default: `'default'`.
+     */
+    variant?: 'default' | 'ghost';
     /** Dropdown horizontal alignment. Default: `'auto'` in compact, `'left'` otherwise. */
     dropdownAlign?: DropdownAlign;
     /**
@@ -21065,6 +21359,33 @@ export declare interface NiceTopNavProps {
     userMenu?: NiceTopNavMenuItem[];
     onProfile?: () => void;
     onLogout?: () => void;
+    /**
+     * Whether to render the workspace `<select>` row above the navigation tree
+     * in the hamburger pull-down panel. Visibility is ALWAYS prop-controlled
+     * (not auto-derived from `mobilePanels.length`) — consumers decide when it
+     * makes sense to show it. Requires signed-in `user`. Default: `false`.
+     */
+    showMobilePanelSelector?: boolean;
+    /** List of panels/workspaces the user has access to. */
+    mobilePanels?: Array<{
+        id: string;
+        label: string;
+        icon?: default_2.ReactNode;
+    }>;
+    /** Currently active panel id (controls the workspace `<select>` value). */
+    activeMobilePanelId?: string;
+    /** Notified when user picks a different panel from the workspace selector. */
+    onMobilePanelChange?: (id: string) => void;
+    /**
+     * Render a mode toolbar (favorites / all / …) row above the navigation
+     * in the hamburger pull-down panel. Requires signed-in `user`. NOTE: when
+     * panel renders `<NiceSidebarNav embedded enableModeIcons>` (i.e. you
+     * pass `sidebarData`), the sidebar already has its own mode strip — leave
+     * this `false` for that branch to avoid a duplicate bar. Default: `false`.
+     */
+    showMobilePanelModes?: boolean;
+    /** Optional custom mode toolbar; replaces the default cosmetic pills. */
+    mobilePanelModes?: default_2.ReactNode;
     showLogin?: boolean;
     loginLabel?: string;
     onLoginClick?: () => void;
@@ -21086,6 +21407,16 @@ export declare interface NiceTopNavProps {
     settingsMenuItems?: UserMenuItem[];
     /** Settings button aria-label / tooltip. */
     settingsLabel?: string;
+    /**
+     * Show a built-in `?` help button in the right cluster. Used by
+     * `NiceNavShell` to launch the contextual help walkthrough.
+     * Default `false`.
+     */
+    showHelpButton?: boolean;
+    /** Help button click handler — required when `showHelpButton` is true. */
+    onHelpClick?: () => void;
+    /** Help button aria-label / tooltip. Defaults to translated "Help". */
+    helpLabel?: string;
     /**
      * Wrap search + language + theme pickers in a collapsible cluster with a
      * chevron toggle. When `true` (default), the cluster starts collapsed and
@@ -21098,6 +21429,26 @@ export declare interface NiceTopNavProps {
     rightClusterDefaultOpen?: boolean;
     leftContent?: default_2.ReactNode;
     rightContent?: default_2.ReactNode;
+    /**
+     * Full navigation data shared with `NiceSidebarNav`. When provided, the
+     * hamburger drawer renders an embedded `NiceSidebarNav` (full mode strip +
+     * multi-level tree + search/favorites/preferences) instead of the legacy
+     * flat menu. Lets a parent shell drive both the desktop sidebar and the
+     * mobile hamburger from one model.
+     */
+    sidebarData?: SidebarNavDataNode[];
+    /** User id forwarded to the embedded `NiceSidebarNav` (preferences scope). */
+    sidebarUserId?: string;
+    /** Active route highlighted in the mobile sidebar drawer. */
+    sidebarActiveRoute?: string;
+    /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. */
+    onSidebarNavigate?: (route: string, view: SidebarNavView) => void;
+    /**
+     * Force the narrow "2-row" mobile layout regardless of viewport width. Use
+     * from `NiceNavShell` to keep the breakpoint decision in one place when the
+     * shell already hides the sidebar.
+     */
+    forceMobileLayout?: boolean;
     className?: string;
     style?: default_2.CSSProperties;
     id?: string;
@@ -21381,6 +21732,11 @@ export declare interface NiceTreeSelectProps extends NiceFormFieldProps {
     /** Only allow selection of leaf nodes */
     selectableLeafsOnly?: boolean;
     clearable?: boolean;
+    /**
+     * Maximum nesting depth rendered (1..10). Beyond this, nodes are treated as
+     * leaves (children not rendered, no expand toggle). Default: unlimited.
+     */
+    maxDepth?: number;
 }
 
 export declare const NiceTreeView: default_2.FC<NiceTreeViewProps>;
@@ -21427,6 +21783,11 @@ export declare interface NiceTreeViewProps extends NiceBaseProps {
     editable?: boolean;
     /** Called when a node label is edited. */
     onNodeEdit?: (key: string, newText: string) => void;
+    /**
+     * Maximum nesting depth rendered (1..10). Beyond this, nodes are treated as
+     * leaves (children not rendered, no expand toggle). Default: unlimited.
+     */
+    maxDepth?: number;
 }
 
 /**
@@ -23603,6 +23964,9 @@ export { PreferencesStorageAdapter }
 
 export { PreferencesSyncAdapter }
 
+/** Ordered list of preference categories rendered as a navigable tree. */
+export declare const PREFS_CATEGORIES: SidebarPrefsCategory[];
+
 /**
  * Preload all heavy components
  *
@@ -24945,6 +25309,9 @@ export declare type ShapeType = 'rectangle' | 'ellipse' | 'polygon' | 'freehand'
 
 export declare const ShopifyConnector: ConnectorDefinition;
 
+/** Route keys produced by {@link buildSidebarPrefsRoutes}. */
+export declare const SIDEBAR_PREFS_ROUTE_KEYS: ReadonlyArray<string>;
+
 /**
  * Top-level data node: one data source with all its navigation children.
  * modules  → used in 'all' mode     (depth: source → module → view)
@@ -24983,6 +25350,26 @@ export declare interface SidebarNavFavorite {
     addedAt: number;
 }
 
+export declare interface SidebarNavHelpers {
+    setMode: (mode: SidebarNavMode) => void;
+    setEnableModeIcons: (enabled: boolean) => void;
+    toggleMode: (mode: SidebarNavMode) => void;
+    pinSource: (mode: SidebarNavMode, sourceId: string) => void;
+    unpinSource: (mode: SidebarNavMode, sourceId: string) => void;
+    hideItem: (item: SidebarNavHiddenItem) => void;
+    restoreItem: (id: string) => void;
+    addFavorite: (fav: SidebarNavFavorite) => void;
+    removeFavorite: (id: string) => void;
+    setMaxDepth: (mode: SidebarNavMode, depth: number) => void;
+    toggleCollapse: (nodeId: string) => void;
+    setAutoExpand: (v: boolean) => void;
+    /** Set the user's preferred left-click behaviour for sidebar items. */
+    setLeftClickBehavior: (v: 'focus-existing' | 'open-new') => void;
+    /** Replace the per-mode ordering of item ids. Pass `null` to clear (revert to data-defined order). */
+    reorderItems: (mode: SidebarNavMode, orderedIds: string[] | null) => void;
+    resetAll: () => void;
+}
+
 export declare interface SidebarNavHiddenItem {
     /** The id of the hidden entity (source/module/view/role/unit id) */
     id: string;
@@ -24993,7 +25380,7 @@ export declare interface SidebarNavHiddenItem {
 }
 
 /** Display mode for the sidebar navigation */
-export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites' | 'preferences';
+export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites' | 'search' | 'preferences';
 
 /** A module containing multiple views */
 export declare interface SidebarNavModule {
@@ -25050,6 +25437,22 @@ export declare interface SidebarNavUserPrefs {
     collapsedIds: string[];
     /** Start everything expanded (default: true) */
     autoExpand: boolean;
+    /**
+     * What left-click does when the route is already open in a tab.
+     * - `'focus-existing'` (default): focus the existing tab (no duplicate)
+     * - `'open-new'`: always open a new tab (duplicates allowed)
+     *
+     * Communicated to the host via the third arg of `onNavigate`
+     * (`{ forceNew: boolean }`). NavShell honours it when
+     * `autoOpenSidebarRoutes` is enabled.
+     */
+    leftClickBehavior: 'focus-existing' | 'open-new';
+    /**
+     * User-chosen ordering of item ids for each mode. Items not present
+     * keep their original (data-defined) order after the listed ones.
+     * Edited from the "Order" page in preferences.
+     */
+    itemOrder: Partial<Record<SidebarNavMode, string[]>>;
 }
 
 /** A single navigable view / entity view */
@@ -25066,6 +25469,39 @@ export declare interface SidebarNavView {
     moduleId?: string;
 }
 
+/**
+ * Definition of a single navigable preferences category. Mirrors the shape
+ * of a `SidebarNavView` so it can be rendered by the existing sidebar tree
+ * code without special-casing.
+ */
+export declare interface SidebarPrefsCategory {
+    id: string;
+    /** Route key — passed to `onNavigate`. Convention: `preferences/<slug>`. */
+    route: string;
+    /** Translation key for the visible label. */
+    labelKey: string;
+    /** English fallback for the label. */
+    labelDefault: string;
+    /** Inline SVG icon node. */
+    icon: ReactNode;
+}
+
+export declare function SidebarPrefsScopeProvider({ userId, data, children, }: SidebarPrefsScopeProviderProps): default_2.ReactElement;
+
+export declare interface SidebarPrefsScopeProviderProps extends SidebarPrefsScopeValue {
+    children: ReactNode;
+}
+
+/**
+ * Shared scope wiring needed by the preferences pages rendered as NavShell
+ * routes. NavShell sets this whenever `sidebarUserId` and/or `sidebarData`
+ * are provided; pages also accept explicit prop overrides.
+ */
+export declare interface SidebarPrefsScopeValue {
+    userId?: string;
+    data?: SidebarNavDataNode[];
+}
+
 export declare interface SignalRLiveChartSourceConfig {
     /** SignalR hub connection. */
     hubConnection: {
@@ -27374,6 +27810,14 @@ export { useShowAt }
 
 export { UseShowAtOptions }
 
+export declare function useSidebarNavPrefs(userId: string | undefined, initialEnableModeIcons: boolean | undefined, controlledPrefs: Partial<SidebarNavUserPrefs> | undefined, onChange: ((prefs: SidebarNavUserPrefs) => void) | undefined): [SidebarNavUserPrefs, SidebarNavHelpers];
+
+/** Resolve `{ userId, data }` for a preferences page. Props override context. */
+export declare function useSidebarPrefsScope(overrides?: SidebarPrefsScopeValue): SidebarPrefsScopeValue;
+
+/** Shortcut for pages that only need the userId. */
+export declare function useSidebarUserId(override?: string): string | undefined;
+
 /**
  * Hook to get a namespaced storage adapter.
  */