@nice2dev/ui 1.0.19 → 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;
@@ -15672,7 +15687,9 @@ export declare interface NiceNavShellApi {
      *  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>) => void;
+    openRoute: (route: string, opts?: Partial<NiceNavShellTab> & {
+        forceNew?: boolean;
+    }) => void;
     closeTab: (id: string) => void;
     closeOthers: (id: string) => void;
     closeAll: () => void;
@@ -15680,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 {
@@ -15706,8 +15776,37 @@ export declare interface NiceNavShellProps {
     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). */
-    onSidebarNavigate?: (route: string, view: SidebarNavView) => void;
+    /**
+     * 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
@@ -15768,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;
@@ -18986,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.
@@ -19047,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>>;
@@ -21219,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
@@ -23766,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
  *
@@ -25108,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)
@@ -25146,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;
@@ -25213,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 */
@@ -25229,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: {
@@ -27537,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.
  */