@nice2dev/ui 1.3.1 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -5174,6 +5174,9 @@ export { FilterToSqlOptions }
5174
5174
 
5175
5175
  export declare type FilterType = 'brightness' | 'contrast' | 'saturation' | 'hue' | 'blur' | 'sharpen' | 'grayscale' | 'sepia' | 'invert' | 'vignette' | 'chromaKey' | 'colorCorrection';
5176
5176
 
5177
+ /** The first view with `route`, searched in every tree unless `options.trees` says otherwise. */
5178
+ export declare function findSidebarItemByRoute(data: readonly SidebarNavDataNode[], route: string, options?: WalkSidebarNavOptions): SidebarNavVisit<SidebarNavView> | undefined;
5179
+
5177
5180
  /**
5178
5181
  * Heraldically-correct flag icon rendered from `country-flag-icons` SVGs
5179
5182
  * (3:2 aspect ratio). Falls back to a coloured stripe swatch when the
@@ -6766,6 +6769,12 @@ export declare interface MapRegion {
6766
6769
  metadata?: Record<string, any>;
6767
6770
  }
6768
6771
 
6772
+ /**
6773
+ * A copy of `data` with `fn` applied to every view, nested ones included — e.g. to add badges.
6774
+ * Return the view itself to keep it as it is.
6775
+ */
6776
+ export declare function mapSidebarViews(data: readonly SidebarNavDataNode[], fn: (view: SidebarNavView, depth: number) => SidebarNavView): SidebarNavDataNode[];
6777
+
6769
6778
  /** Marker category */
6770
6779
  export declare type MarkerCategory = 'note' | 'issue' | 'question' | 'chapter' | 'highlight' | 'action' | 'custom';
6771
6780
 
@@ -17212,6 +17221,12 @@ export declare interface NiceNavShellApi {
17212
17221
  openRoute: (route: string, opts?: Partial<NiceNavShellTab> & {
17213
17222
  forceNew?: boolean;
17214
17223
  }) => void;
17224
+ /**
17225
+ * Open what a sidebar item points to as the built-in sidebar does (1.3.2): the item's label and
17226
+ * icon, a new tab when `opts.forceNew`, the colour `tabColors` picks. For a `sidebar` slot of your
17227
+ * own: `onNavigate={(route, view, opts) => api.openFromSidebar(route, view, opts)}`.
17228
+ */
17229
+ openFromSidebar: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
17215
17230
  closeTab: (id: string) => void;
17216
17231
  closeOthers: (id: string) => void;
17217
17232
  closeAll: () => void;
@@ -17306,9 +17321,7 @@ export declare interface NiceNavShellProps {
17306
17321
  * used). NavShell honours it automatically when `autoOpenSidebarRoutes`
17307
17322
  * is enabled — handlers can ignore it for backward compat.
17308
17323
  */
17309
- onSidebarNavigate?: (route: string, view: SidebarNavView, opts?: {
17310
- forceNew?: boolean;
17311
- }) => void;
17324
+ onSidebarNavigate?: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
17312
17325
  /**
17313
17326
  * When true (default when tabs are enabled), NavShell auto-calls
17314
17327
  * `openRoute(route, { forceNew })` whenever the sidebar fires
@@ -17316,6 +17329,14 @@ export declare interface NiceNavShellProps {
17316
17329
  * navigation manually" behaviour.
17317
17330
  */
17318
17331
  autoOpenSidebarRoutes?: boolean;
17332
+ /**
17333
+ * Which colour tabs opened from the sidebar take (1.3.2): `'none'` (default), `'branch'` — the
17334
+ * colour of the sidebar branch the item belongs to (e.g. its database), `'level'` — the clicked
17335
+ * row's own colour. Applies to the built-in sidebar and to `api.openFromSidebar`.
17336
+ */
17337
+ tabColors?: NiceNavShellTabColors;
17338
+ /** Extra props for the built-in NiceSidebarNav (rendered from `sidebarData`), e.g. `levelColors`. */
17339
+ sidebarProps?: Partial<NiceSidebarNavProps>;
17319
17340
  /**
17320
17341
  * Resolves a route key to a URL. Forwarded to the auto-rendered
17321
17342
  * `NiceSidebarNav` so its right-click context menu can show "Open in
@@ -17485,8 +17506,23 @@ export declare interface NiceNavShellTab {
17485
17506
  dirty?: boolean;
17486
17507
  /** Per-tab override of `closableTabs`. */
17487
17508
  closable?: boolean;
17509
+ /**
17510
+ * Colour of the tab (1.3.2) — a bar along its top edge and a light tint; the active tab stronger.
17511
+ * E.g. the colour of the database a sidebar branch stands for (see `tabColors`). Kept with the
17512
+ * persisted tabs.
17513
+ */
17514
+ color?: string;
17488
17515
  }
17489
17516
 
17517
+ /**
17518
+ * Which colour tabs opened from the sidebar take (1.3.2):
17519
+ * - `'none'` (default) — none;
17520
+ * - `'branch'` — the colour of the nearest sidebar branch with its own `color` / `levelColors`
17521
+ * (`opts.branchColor`), e.g. the database a source stands for;
17522
+ * - `'level'` — the clicked row's own colour, level colours included (`opts.color`).
17523
+ */
17524
+ export declare type NiceNavShellTabColors = 'none' | 'branch' | 'level';
17525
+
17490
17526
  export declare type NiceNavShellTabsAnimation = 'none' | 'fade' | 'slide';
17491
17527
 
17492
17528
  export declare const NiceNetworkDiscoveryPanel: default_2.FC<NiceNetworkDiscoveryPanelProps>;
@@ -20897,9 +20933,19 @@ export declare interface NiceSidebarNavProps {
20897
20933
  * — e.g. a single-pane layout — can ignore the third argument; nothing else
20898
20934
  * changes for them.
20899
20935
  */
20900
- onNavigate?: (route: string, view: SidebarNavView, opts?: {
20901
- forceNew?: boolean;
20902
- }) => void;
20936
+ onNavigate?: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
20937
+ /**
20938
+ * Colours per level for the whole tree (1.3.2): `[0]` is the source header, `[1]` the first level
20939
+ * under it, and so on; levels past the end take tints of the last colour. Each row gets its
20940
+ * level's colour as a full background with readable text. A branch's own `color` / `levelColors`
20941
+ * overrides it for that subtree.
20942
+ */
20943
+ levelColors?: string[];
20944
+ /**
20945
+ * Which way the deeper levels of a colour go: `'tint'` (towards white), `'shade'` (towards black)
20946
+ * or `'auto'` (default) — shades in a dark theme, tints otherwise.
20947
+ */
20948
+ levelShading?: 'auto' | 'tint' | 'shade';
20903
20949
  /**
20904
20950
  * Resolves a route key to a URL. When provided, the right-click menu shows
20905
20951
  * "Open in new browser tab" (via `window.open`) and "Copy link". When
@@ -23123,8 +23169,9 @@ export declare interface NiceTopNavProps {
23123
23169
  sidebarUserId?: string;
23124
23170
  /** Active route highlighted in the mobile sidebar drawer. */
23125
23171
  sidebarActiveRoute?: string;
23126
- /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. */
23127
- onSidebarNavigate?: (route: string, view: SidebarNavView) => void;
23172
+ /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. `opts` as in
23173
+ * NiceSidebarNav's `onNavigate` (new tab, colours, path). */
23174
+ onSidebarNavigate?: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
23128
23175
  /**
23129
23176
  * Force the narrow "2-row" mobile layout regardless of viewport width. Use
23130
23177
  * from `NiceNavShell` to keep the breakpoint decision in one place when the
@@ -27042,11 +27089,29 @@ export declare const ShopifyConnector: ConnectorDefinition;
27042
27089
  /** Route keys produced by {@link buildSidebarPrefsRoutes}. */
27043
27090
  export declare const SIDEBAR_PREFS_ROUTE_KEYS: ReadonlyArray<string>;
27044
27091
 
27092
+ declare type SidebarLevelShading = 'tint' | 'shade';
27093
+
27094
+ /**
27095
+ * Colour of a branch (1.3.2), on sources, modules, roles, units and views. The branch's row and
27096
+ * everything under it take the colour as a full row background, each deeper level a tint of it (a
27097
+ * shade in a dark theme), with readable text. Overrides the sidebar's `levelColors` and the colour
27098
+ * of the branches above for this subtree.
27099
+ */
27100
+ export declare interface SidebarNavBranchColors {
27101
+ /** One colour: the branch itself, deeper levels tints of it. Hex or `rgb()` gets the tints and the
27102
+ * readable text; any other CSS colour is used as given on every level. */
27103
+ color?: string;
27104
+ /** Colours per level of this branch, starting with the branch itself; past the end, tints of the
27105
+ * last one. Wins over `color`. */
27106
+ levelColors?: string[];
27107
+ }
27108
+
27045
27109
  /**
27046
27110
  * Top-level data node: one data source with all its navigation children.
27047
- * modules → used in 'all' mode (depth: source → module → view)
27048
- * roles → used in 'by-role' mode (depth: source → role → module → view)
27049
- * units → used in 'by-unit' mode (depth: source → unit → module → view)
27111
+ * modules → used in 'all' mode (depth: source → module → view → …)
27112
+ * roles → used in 'by-role' mode (depth: source → role → module → view → …)
27113
+ * units → used in 'by-unit' mode (depth: source → unit → module → view → …)
27114
+ * Views nest further through `children`, to any depth.
27050
27115
  */
27051
27116
  export declare interface SidebarNavDataNode {
27052
27117
  source: SidebarNavDataSource;
@@ -27059,13 +27124,12 @@ export declare interface SidebarNavDataNode {
27059
27124
  }
27060
27125
 
27061
27126
  /** A database / API instance that can be pinned per mode */
27062
- export declare interface SidebarNavDataSource {
27127
+ export declare interface SidebarNavDataSource extends SidebarNavBranchColors {
27063
27128
  id: string;
27064
27129
  label: string;
27065
27130
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27066
27131
  tooltip?: ReactNode;
27067
27132
  icon?: ReactNode;
27068
- color?: string;
27069
27133
  /** Server URL or connection string hint */
27070
27134
  url?: string;
27071
27135
  type?: 'database' | 'instance' | 'api' | 'other';
@@ -27081,6 +27145,9 @@ export declare interface SidebarNavFavorite {
27081
27145
  route?: string;
27082
27146
  sourceId?: string;
27083
27147
  moduleId?: string;
27148
+ /** Branch colour of the item when it was added (1.3.2) — the favorites list shows it and passes it
27149
+ * on in `onNavigate`. */
27150
+ color?: string;
27084
27151
  addedAt: number;
27085
27152
  }
27086
27153
 
@@ -27114,11 +27181,13 @@ export declare interface SidebarNavHiddenItem {
27114
27181
  label: string;
27115
27182
  }
27116
27183
 
27184
+ export declare type SidebarNavItem = SidebarNavDataSource | SidebarNavRole | SidebarNavUnit | SidebarNavModule | SidebarNavView;
27185
+
27117
27186
  /** Display mode for the sidebar navigation */
27118
27187
  export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites' | 'search' | 'preferences';
27119
27188
 
27120
27189
  /** A module containing multiple views */
27121
- export declare interface SidebarNavModule {
27190
+ export declare interface SidebarNavModule extends SidebarNavBranchColors {
27122
27191
  id: string;
27123
27192
  label: string;
27124
27193
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27129,8 +27198,29 @@ export declare interface SidebarNavModule {
27129
27198
  sourceId?: string;
27130
27199
  }
27131
27200
 
27201
+ /** Third argument of `onNavigate`. */
27202
+ export declare interface SidebarNavNavigateOptions {
27203
+ /** Open a new tab even when the route is already open — the user's left-click preference or the
27204
+ * "Open in new tab" menu item. */
27205
+ forceNew?: boolean;
27206
+ /** Background of the clicked row: the colour of its level or branch, when one is set (1.3.2). */
27207
+ color?: string;
27208
+ /** Base colour of the nearest branch with its own `color` / `levelColors` — e.g. the database a
27209
+ * source stands for. What NiceNavShell's `tabColors="branch"` paints a tab with (1.3.2). */
27210
+ branchColor?: string;
27211
+ /** Ids and labels from the source down to the clicked item (1.3.2). */
27212
+ path?: SidebarNavPathEntry[];
27213
+ }
27214
+
27215
+ /** One step of the path from the source down to an item. */
27216
+ export declare interface SidebarNavPathEntry {
27217
+ id: string;
27218
+ label: string;
27219
+ icon?: ReactNode;
27220
+ }
27221
+
27132
27222
  /** A role grouping modules */
27133
- export declare interface SidebarNavRole {
27223
+ export declare interface SidebarNavRole extends SidebarNavBranchColors {
27134
27224
  id: string;
27135
27225
  label: string;
27136
27226
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27141,8 +27231,11 @@ export declare interface SidebarNavRole {
27141
27231
  sourceId?: string;
27142
27232
  }
27143
27233
 
27234
+ /** The three trees of a data node: `modules` (the "All" mode), `roles`, `units`. */
27235
+ export declare type SidebarNavTreeName = 'modules' | 'roles' | 'units';
27236
+
27144
27237
  /** An organizational unit grouping modules */
27145
- export declare interface SidebarNavUnit {
27238
+ export declare interface SidebarNavUnit extends SidebarNavBranchColors {
27146
27239
  id: string;
27147
27240
  label: string;
27148
27241
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27170,8 +27263,8 @@ export declare interface SidebarNavUserPrefs {
27170
27263
  hiddenItems: SidebarNavHiddenItem[];
27171
27264
  favorites: SidebarNavFavorite[];
27172
27265
  /**
27173
- * How many levels to show per mode.
27174
- * 1 = sources only, 2 = sources + first level, 3 = …, 4 = all (default)
27266
+ * How many levels to show per mode: 1 = sources only, 2 = sources + first level, 3 = … Absent or
27267
+ * 10 and more = every level (1.3.2; it was 4 before levels could nest).
27175
27268
  */
27176
27269
  maxDepth: Partial<Record<SidebarNavMode, number>>;
27177
27270
  /** IDs that are manually collapsed */
@@ -27196,20 +27289,48 @@ export declare interface SidebarNavUserPrefs {
27196
27289
  itemOrder: Partial<Record<SidebarNavMode, string[]>>;
27197
27290
  }
27198
27291
 
27199
- /** A single navigable view / entity view */
27200
- export declare interface SidebarNavView {
27292
+ /**
27293
+ * A single navigable view / entity view. With `children` it is a group (1.3.2), nested to any
27294
+ * depth. Ids must be unique across the whole tree: collapse state, favorites and hidden items are
27295
+ * kept by id.
27296
+ */
27297
+ export declare interface SidebarNavView extends SidebarNavBranchColors {
27201
27298
  id: string;
27202
27299
  label: string;
27203
27300
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27204
27301
  tooltip?: ReactNode;
27205
27302
  icon?: ReactNode;
27206
- /** Route path for navigation */
27303
+ /**
27304
+ * Route path for navigation. On a group (a view with `children`), clicking the label opens the
27305
+ * route and expands the group; the arrow only expands or collapses it.
27306
+ */
27207
27307
  route?: string;
27208
27308
  /** Badge counter (unread notifications, pending tasks, …) */
27209
27309
  badge?: string | number;
27210
27310
  isExternal?: boolean;
27211
27311
  /** Module this view belongs to */
27212
27312
  moduleId?: string;
27313
+ /** Nested items (1.3.2) — a view with children is a group. */
27314
+ children?: SidebarNavView[];
27315
+ }
27316
+
27317
+ /** One item met by {@link walkSidebarNav}. */
27318
+ export declare interface SidebarNavVisit<T extends SidebarNavItem = SidebarNavItem> {
27319
+ item: T;
27320
+ kind: SidebarNavHiddenItem['kind'];
27321
+ /** The level its row is drawn at: 1 = source, 2 = the first level under it, … */
27322
+ depth: number;
27323
+ /** The items above it, from the source down (itself not included). */
27324
+ ancestors: SidebarNavPathEntry[];
27325
+ sourceId: string;
27326
+ /** The module it belongs to (a module: itself). */
27327
+ moduleId?: string;
27328
+ /** The tree it was met in; absent for the source. */
27329
+ tree?: SidebarNavTreeName;
27330
+ /** Base colour of the nearest branch with its own colour, itself included. */
27331
+ branchColor?: string;
27332
+ /** Background of its row, when levels or branches are coloured. */
27333
+ color?: string;
27213
27334
  }
27214
27335
 
27215
27336
  /**
@@ -30101,6 +30222,21 @@ declare interface WaitCondition {
30101
30222
  timeout?: number;
30102
30223
  }
30103
30224
 
30225
+ /**
30226
+ * Visit every item of `data`, depth first, parents before their children. Return `false` from
30227
+ * `visit` to skip an item's subtree.
30228
+ */
30229
+ export declare function walkSidebarNav(data: readonly SidebarNavDataNode[], visit: (v: SidebarNavVisit) => boolean | void, options?: WalkSidebarNavOptions): void;
30230
+
30231
+ export declare interface WalkSidebarNavOptions {
30232
+ /** Trees to walk. Default `['modules']`. */
30233
+ trees?: SidebarNavTreeName[];
30234
+ /** The sidebar's `levelColors`, so `color` matches the drawn rows. */
30235
+ levelColors?: string[];
30236
+ /** Direction of the tints. Default `'tint'`. */
30237
+ shading?: SidebarLevelShading;
30238
+ }
30239
+
30104
30240
  /** Watermark settings */
30105
30241
  export declare interface WatermarkSettings {
30106
30242
  enabled: boolean;