@nice2dev/ui 1.3.1 → 1.3.3

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,21 @@ 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
+ /**
17339
+ * How a tab shows its colour (1.3.3): `'bar'` — a line under the tab, `'fill'` — a tint with a
17340
+ * bar along the top. Absent: the sidebar's `colorStyle` preference (Preferences → Display) of
17341
+ * `sidebarUserId`, so the tabs follow the user's choice. Pass it when your own `sidebar` keeps
17342
+ * its preferences elsewhere (e.g. on the server).
17343
+ */
17344
+ colorStyle?: 'bar' | 'fill';
17345
+ /** Extra props for the built-in NiceSidebarNav (rendered from `sidebarData`), e.g. `levelColors`. */
17346
+ sidebarProps?: Partial<NiceSidebarNavProps>;
17319
17347
  /**
17320
17348
  * Resolves a route key to a URL. Forwarded to the auto-rendered
17321
17349
  * `NiceSidebarNav` so its right-click context menu can show "Open in
@@ -17485,8 +17513,23 @@ export declare interface NiceNavShellTab {
17485
17513
  dirty?: boolean;
17486
17514
  /** Per-tab override of `closableTabs`. */
17487
17515
  closable?: boolean;
17516
+ /**
17517
+ * Colour of the tab (1.3.2) — a bar along its top edge and a light tint; the active tab stronger.
17518
+ * E.g. the colour of the database a sidebar branch stands for (see `tabColors`). Kept with the
17519
+ * persisted tabs.
17520
+ */
17521
+ color?: string;
17488
17522
  }
17489
17523
 
17524
+ /**
17525
+ * Which colour tabs opened from the sidebar take (1.3.2):
17526
+ * - `'none'` (default) — none;
17527
+ * - `'branch'` — the colour of the nearest sidebar branch with its own `color` / `levelColors`
17528
+ * (`opts.branchColor`), e.g. the database a source stands for;
17529
+ * - `'level'` — the clicked row's own colour, level colours included (`opts.color`).
17530
+ */
17531
+ export declare type NiceNavShellTabColors = 'none' | 'branch' | 'level';
17532
+
17490
17533
  export declare type NiceNavShellTabsAnimation = 'none' | 'fade' | 'slide';
17491
17534
 
17492
17535
  export declare const NiceNetworkDiscoveryPanel: default_2.FC<NiceNetworkDiscoveryPanelProps>;
@@ -20897,9 +20940,19 @@ export declare interface NiceSidebarNavProps {
20897
20940
  * — e.g. a single-pane layout — can ignore the third argument; nothing else
20898
20941
  * changes for them.
20899
20942
  */
20900
- onNavigate?: (route: string, view: SidebarNavView, opts?: {
20901
- forceNew?: boolean;
20902
- }) => void;
20943
+ onNavigate?: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
20944
+ /**
20945
+ * Colours per level for the whole tree (1.3.2): `[0]` is the source header, `[1]` the first level
20946
+ * under it, and so on; levels past the end take tints of the last colour. Each row gets its
20947
+ * level's colour as a full background with readable text. A branch's own `color` / `levelColors`
20948
+ * overrides it for that subtree.
20949
+ */
20950
+ levelColors?: string[];
20951
+ /**
20952
+ * Which way the deeper levels of a colour go: `'tint'` (towards white), `'shade'` (towards black)
20953
+ * or `'auto'` (default) — shades in a dark theme, tints otherwise.
20954
+ */
20955
+ levelShading?: 'auto' | 'tint' | 'shade';
20903
20956
  /**
20904
20957
  * Resolves a route key to a URL. When provided, the right-click menu shows
20905
20958
  * "Open in new browser tab" (via `window.open`) and "Copy link". When
@@ -23123,8 +23176,9 @@ export declare interface NiceTopNavProps {
23123
23176
  sidebarUserId?: string;
23124
23177
  /** Active route highlighted in the mobile sidebar drawer. */
23125
23178
  sidebarActiveRoute?: string;
23126
- /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. */
23127
- onSidebarNavigate?: (route: string, view: SidebarNavView) => void;
23179
+ /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. `opts` as in
23180
+ * NiceSidebarNav's `onNavigate` (new tab, colours, path). */
23181
+ onSidebarNavigate?: (route: string, view: SidebarNavView, opts?: SidebarNavNavigateOptions) => void;
23128
23182
  /**
23129
23183
  * Force the narrow "2-row" mobile layout regardless of viewport width. Use
23130
23184
  * from `NiceNavShell` to keep the breakpoint decision in one place when the
@@ -27042,11 +27096,29 @@ export declare const ShopifyConnector: ConnectorDefinition;
27042
27096
  /** Route keys produced by {@link buildSidebarPrefsRoutes}. */
27043
27097
  export declare const SIDEBAR_PREFS_ROUTE_KEYS: ReadonlyArray<string>;
27044
27098
 
27099
+ declare type SidebarLevelShading = 'tint' | 'shade';
27100
+
27101
+ /**
27102
+ * Colour of a branch (1.3.2), on sources, modules, roles, units and views. The branch's row and
27103
+ * everything under it take the colour as a full row background, each deeper level a tint of it (a
27104
+ * shade in a dark theme), with readable text. Overrides the sidebar's `levelColors` and the colour
27105
+ * of the branches above for this subtree.
27106
+ */
27107
+ export declare interface SidebarNavBranchColors {
27108
+ /** One colour: the branch itself, deeper levels tints of it. Hex or `rgb()` gets the tints and the
27109
+ * readable text; any other CSS colour is used as given on every level. */
27110
+ color?: string;
27111
+ /** Colours per level of this branch, starting with the branch itself; past the end, tints of the
27112
+ * last one. Wins over `color`. */
27113
+ levelColors?: string[];
27114
+ }
27115
+
27045
27116
  /**
27046
27117
  * 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)
27118
+ * modules → used in 'all' mode (depth: source → module → view → …)
27119
+ * roles → used in 'by-role' mode (depth: source → role → module → view → …)
27120
+ * units → used in 'by-unit' mode (depth: source → unit → module → view → …)
27121
+ * Views nest further through `children`, to any depth.
27050
27122
  */
27051
27123
  export declare interface SidebarNavDataNode {
27052
27124
  source: SidebarNavDataSource;
@@ -27059,13 +27131,12 @@ export declare interface SidebarNavDataNode {
27059
27131
  }
27060
27132
 
27061
27133
  /** A database / API instance that can be pinned per mode */
27062
- export declare interface SidebarNavDataSource {
27134
+ export declare interface SidebarNavDataSource extends SidebarNavBranchColors {
27063
27135
  id: string;
27064
27136
  label: string;
27065
27137
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27066
27138
  tooltip?: ReactNode;
27067
27139
  icon?: ReactNode;
27068
- color?: string;
27069
27140
  /** Server URL or connection string hint */
27070
27141
  url?: string;
27071
27142
  type?: 'database' | 'instance' | 'api' | 'other';
@@ -27081,6 +27152,9 @@ export declare interface SidebarNavFavorite {
27081
27152
  route?: string;
27082
27153
  sourceId?: string;
27083
27154
  moduleId?: string;
27155
+ /** Branch colour of the item when it was added (1.3.2) — the favorites list shows it and passes it
27156
+ * on in `onNavigate`. */
27157
+ color?: string;
27084
27158
  addedAt: number;
27085
27159
  }
27086
27160
 
@@ -27102,6 +27176,8 @@ export declare interface SidebarNavHelpers {
27102
27176
  setLeftClickBehavior: (v: 'focus-existing' | 'open-new') => void;
27103
27177
  /** Replace the per-mode ordering of item ids. Pass `null` to clear (revert to data-defined order). */
27104
27178
  reorderItems: (mode: SidebarNavMode, orderedIds: string[] | null) => void;
27179
+ /** How level / branch colours show: a bar by each row (default) or the whole row filled. */
27180
+ setColorStyle: (v: 'bar' | 'fill') => void;
27105
27181
  resetAll: () => void;
27106
27182
  }
27107
27183
 
@@ -27114,11 +27190,13 @@ export declare interface SidebarNavHiddenItem {
27114
27190
  label: string;
27115
27191
  }
27116
27192
 
27193
+ export declare type SidebarNavItem = SidebarNavDataSource | SidebarNavRole | SidebarNavUnit | SidebarNavModule | SidebarNavView;
27194
+
27117
27195
  /** Display mode for the sidebar navigation */
27118
27196
  export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites' | 'search' | 'preferences';
27119
27197
 
27120
27198
  /** A module containing multiple views */
27121
- export declare interface SidebarNavModule {
27199
+ export declare interface SidebarNavModule extends SidebarNavBranchColors {
27122
27200
  id: string;
27123
27201
  label: string;
27124
27202
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27129,8 +27207,29 @@ export declare interface SidebarNavModule {
27129
27207
  sourceId?: string;
27130
27208
  }
27131
27209
 
27210
+ /** Third argument of `onNavigate`. */
27211
+ export declare interface SidebarNavNavigateOptions {
27212
+ /** Open a new tab even when the route is already open — the user's left-click preference or the
27213
+ * "Open in new tab" menu item. */
27214
+ forceNew?: boolean;
27215
+ /** Background of the clicked row: the colour of its level or branch, when one is set (1.3.2). */
27216
+ color?: string;
27217
+ /** Base colour of the nearest branch with its own `color` / `levelColors` — e.g. the database a
27218
+ * source stands for. What NiceNavShell's `tabColors="branch"` paints a tab with (1.3.2). */
27219
+ branchColor?: string;
27220
+ /** Ids and labels from the source down to the clicked item (1.3.2). */
27221
+ path?: SidebarNavPathEntry[];
27222
+ }
27223
+
27224
+ /** One step of the path from the source down to an item. */
27225
+ export declare interface SidebarNavPathEntry {
27226
+ id: string;
27227
+ label: string;
27228
+ icon?: ReactNode;
27229
+ }
27230
+
27132
27231
  /** A role grouping modules */
27133
- export declare interface SidebarNavRole {
27232
+ export declare interface SidebarNavRole extends SidebarNavBranchColors {
27134
27233
  id: string;
27135
27234
  label: string;
27136
27235
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27141,8 +27240,11 @@ export declare interface SidebarNavRole {
27141
27240
  sourceId?: string;
27142
27241
  }
27143
27242
 
27243
+ /** The three trees of a data node: `modules` (the "All" mode), `roles`, `units`. */
27244
+ export declare type SidebarNavTreeName = 'modules' | 'roles' | 'units';
27245
+
27144
27246
  /** An organizational unit grouping modules */
27145
- export declare interface SidebarNavUnit {
27247
+ export declare interface SidebarNavUnit extends SidebarNavBranchColors {
27146
27248
  id: string;
27147
27249
  label: string;
27148
27250
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27170,8 +27272,8 @@ export declare interface SidebarNavUserPrefs {
27170
27272
  hiddenItems: SidebarNavHiddenItem[];
27171
27273
  favorites: SidebarNavFavorite[];
27172
27274
  /**
27173
- * How many levels to show per mode.
27174
- * 1 = sources only, 2 = sources + first level, 3 = …, 4 = all (default)
27275
+ * How many levels to show per mode: 1 = sources only, 2 = sources + first level, 3 = … Absent or
27276
+ * 10 and more = every level (1.3.2; it was 4 before levels could nest).
27175
27277
  */
27176
27278
  maxDepth: Partial<Record<SidebarNavMode, number>>;
27177
27279
  /** IDs that are manually collapsed */
@@ -27194,22 +27296,61 @@ export declare interface SidebarNavUserPrefs {
27194
27296
  * Edited from the "Order" page in preferences.
27195
27297
  */
27196
27298
  itemOrder: Partial<Record<SidebarNavMode, string[]>>;
27299
+ /**
27300
+ * How a level / branch colour shows (1.3.3; `levelColors`, a branch's `color`):
27301
+ * - `'bar'` (default): a bar in the colour left of each row's arrow, and NavShell's tabs
27302
+ * underlined in it;
27303
+ * - `'fill'`: the whole row filled with it (text picked for contrast), and the tabs tinted
27304
+ * with a bar along the top — the look of 1.3.2.
27305
+ *
27306
+ * Set from the Display page of the preferences; `preferences={{ colorStyle: 'fill' }}` makes
27307
+ * `'fill'` the default.
27308
+ */
27309
+ colorStyle: 'bar' | 'fill';
27197
27310
  }
27198
27311
 
27199
- /** A single navigable view / entity view */
27200
- export declare interface SidebarNavView {
27312
+ /**
27313
+ * A single navigable view / entity view. With `children` it is a group (1.3.2), nested to any
27314
+ * depth. Ids must be unique across the whole tree: collapse state, favorites and hidden items are
27315
+ * kept by id.
27316
+ */
27317
+ export declare interface SidebarNavView extends SidebarNavBranchColors {
27201
27318
  id: string;
27202
27319
  label: string;
27203
27320
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27204
27321
  tooltip?: ReactNode;
27205
27322
  icon?: ReactNode;
27206
- /** Route path for navigation */
27323
+ /**
27324
+ * Route path for navigation. On a group (a view with `children`), clicking the label opens the
27325
+ * route and expands the group; the arrow only expands or collapses it.
27326
+ */
27207
27327
  route?: string;
27208
27328
  /** Badge counter (unread notifications, pending tasks, …) */
27209
27329
  badge?: string | number;
27210
27330
  isExternal?: boolean;
27211
27331
  /** Module this view belongs to */
27212
27332
  moduleId?: string;
27333
+ /** Nested items (1.3.2) — a view with children is a group. */
27334
+ children?: SidebarNavView[];
27335
+ }
27336
+
27337
+ /** One item met by {@link walkSidebarNav}. */
27338
+ export declare interface SidebarNavVisit<T extends SidebarNavItem = SidebarNavItem> {
27339
+ item: T;
27340
+ kind: SidebarNavHiddenItem['kind'];
27341
+ /** The level its row is drawn at: 1 = source, 2 = the first level under it, … */
27342
+ depth: number;
27343
+ /** The items above it, from the source down (itself not included). */
27344
+ ancestors: SidebarNavPathEntry[];
27345
+ sourceId: string;
27346
+ /** The module it belongs to (a module: itself). */
27347
+ moduleId?: string;
27348
+ /** The tree it was met in; absent for the source. */
27349
+ tree?: SidebarNavTreeName;
27350
+ /** Base colour of the nearest branch with its own colour, itself included. */
27351
+ branchColor?: string;
27352
+ /** Background of its row, when levels or branches are coloured. */
27353
+ color?: string;
27213
27354
  }
27214
27355
 
27215
27356
  /**
@@ -30101,6 +30242,21 @@ declare interface WaitCondition {
30101
30242
  timeout?: number;
30102
30243
  }
30103
30244
 
30245
+ /**
30246
+ * Visit every item of `data`, depth first, parents before their children. Return `false` from
30247
+ * `visit` to skip an item's subtree.
30248
+ */
30249
+ export declare function walkSidebarNav(data: readonly SidebarNavDataNode[], visit: (v: SidebarNavVisit) => boolean | void, options?: WalkSidebarNavOptions): void;
30250
+
30251
+ export declare interface WalkSidebarNavOptions {
30252
+ /** Trees to walk. Default `['modules']`. */
30253
+ trees?: SidebarNavTreeName[];
30254
+ /** The sidebar's `levelColors`, so `color` matches the drawn rows. */
30255
+ levelColors?: string[];
30256
+ /** Direction of the tints. Default `'tint'`. */
30257
+ shading?: SidebarLevelShading;
30258
+ }
30259
+
30104
30260
  /** Watermark settings */
30105
30261
  export declare interface WatermarkSettings {
30106
30262
  enabled: boolean;