@nice2dev/ui 1.3.0 → 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
@@ -17424,6 +17445,15 @@ export declare interface NiceNavShellProps {
17424
17445
  * `--nice-shell-surface-alpha` CSS variable.
17425
17446
  */
17426
17447
  surfaceOpacity?: number;
17448
+ /**
17449
+ * Height of the shell (1.3.1) — px or any CSS length. Default `100%`, which fills a parent with
17450
+ * a definite height. Under a parent that only has `min-height` (a page wrapper with
17451
+ * `min-height: 100vh`), 100% is the height of the content: the shell grows with the page,
17452
+ * nothing scrolls inside it, and the sticky header / footer rows and the sidebar's collapse
17453
+ * button move down with the content. Give the shell a definite height then — `'100dvh'` when it
17454
+ * is the whole page, a number — or give its parent one.
17455
+ */
17456
+ height?: number | string;
17427
17457
  className?: string;
17428
17458
  contentClassName?: string;
17429
17459
  'data-testid'?: string;
@@ -17476,8 +17506,23 @@ export declare interface NiceNavShellTab {
17476
17506
  dirty?: boolean;
17477
17507
  /** Per-tab override of `closableTabs`. */
17478
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;
17479
17515
  }
17480
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
+
17481
17526
  export declare type NiceNavShellTabsAnimation = 'none' | 'fade' | 'slide';
17482
17527
 
17483
17528
  export declare const NiceNetworkDiscoveryPanel: default_2.FC<NiceNetworkDiscoveryPanelProps>;
@@ -20782,6 +20827,14 @@ export declare interface NiceSetupWizardProps {
20782
20827
  };
20783
20828
  /** Accessibility */
20784
20829
  accessMode?: NiceAccessMode;
20830
+ /**
20831
+ * Height of the wizard (1.3.1) — px or any CSS length. Default: as tall as the step, up to the
20832
+ * screen (`max-height: 100vh`), so on a short step the button bar sits right under it. With a
20833
+ * height the wizard fills exactly that (no 400px minimum, no 100vh cap): the step body scrolls
20834
+ * and the button bar stays at the bottom edge on every step. `'100%'` fills a parent with a
20835
+ * definite height, `'100dvh'` the screen.
20836
+ */
20837
+ height?: number | string;
20785
20838
  id?: string;
20786
20839
  className?: string;
20787
20840
  style?: default_2.CSSProperties;
@@ -20880,9 +20933,19 @@ export declare interface NiceSidebarNavProps {
20880
20933
  * — e.g. a single-pane layout — can ignore the third argument; nothing else
20881
20934
  * changes for them.
20882
20935
  */
20883
- onNavigate?: (route: string, view: SidebarNavView, opts?: {
20884
- forceNew?: boolean;
20885
- }) => 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';
20886
20949
  /**
20887
20950
  * Resolves a route key to a URL. When provided, the right-click menu shows
20888
20951
  * "Open in new browser tab" (via `window.open`) and "Copy link". When
@@ -22585,7 +22648,8 @@ export declare interface NiceThemePickerProps extends NiceFormFieldProps, DualVi
22585
22648
  previewSize?: number;
22586
22649
  /**
22587
22650
  * Preview rendering style:
22588
- * - `'page'` (default): a small "page" thumbnail with header/text/sidebar.
22651
+ * - `'page'` (default): a page in miniature — accent bar on top, a card with two lines of text
22652
+ * between thin margins of the page background.
22589
22653
  * - `'swatch'`: a flag-like vertical colour stripe (cheaper, less informative).
22590
22654
  */
22591
22655
  previewShape?: 'page' | 'swatch';
@@ -23105,8 +23169,9 @@ export declare interface NiceTopNavProps {
23105
23169
  sidebarUserId?: string;
23106
23170
  /** Active route highlighted in the mobile sidebar drawer. */
23107
23171
  sidebarActiveRoute?: string;
23108
- /** Fired when a view is clicked in the mobile sidebar drawer. Closes the drawer. */
23109
- 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;
23110
23175
  /**
23111
23176
  * Force the narrow "2-row" mobile layout regardless of viewport width. Use
23112
23177
  * from `NiceNavShell` to keep the breakpoint decision in one place when the
@@ -27024,11 +27089,29 @@ export declare const ShopifyConnector: ConnectorDefinition;
27024
27089
  /** Route keys produced by {@link buildSidebarPrefsRoutes}. */
27025
27090
  export declare const SIDEBAR_PREFS_ROUTE_KEYS: ReadonlyArray<string>;
27026
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
+
27027
27109
  /**
27028
27110
  * Top-level data node: one data source with all its navigation children.
27029
- * modules → used in 'all' mode (depth: source → module → view)
27030
- * roles → used in 'by-role' mode (depth: source → role → module → view)
27031
- * 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.
27032
27115
  */
27033
27116
  export declare interface SidebarNavDataNode {
27034
27117
  source: SidebarNavDataSource;
@@ -27041,13 +27124,12 @@ export declare interface SidebarNavDataNode {
27041
27124
  }
27042
27125
 
27043
27126
  /** A database / API instance that can be pinned per mode */
27044
- export declare interface SidebarNavDataSource {
27127
+ export declare interface SidebarNavDataSource extends SidebarNavBranchColors {
27045
27128
  id: string;
27046
27129
  label: string;
27047
27130
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27048
27131
  tooltip?: ReactNode;
27049
27132
  icon?: ReactNode;
27050
- color?: string;
27051
27133
  /** Server URL or connection string hint */
27052
27134
  url?: string;
27053
27135
  type?: 'database' | 'instance' | 'api' | 'other';
@@ -27063,6 +27145,9 @@ export declare interface SidebarNavFavorite {
27063
27145
  route?: string;
27064
27146
  sourceId?: string;
27065
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;
27066
27151
  addedAt: number;
27067
27152
  }
27068
27153
 
@@ -27096,11 +27181,13 @@ export declare interface SidebarNavHiddenItem {
27096
27181
  label: string;
27097
27182
  }
27098
27183
 
27184
+ export declare type SidebarNavItem = SidebarNavDataSource | SidebarNavRole | SidebarNavUnit | SidebarNavModule | SidebarNavView;
27185
+
27099
27186
  /** Display mode for the sidebar navigation */
27100
27187
  export declare type SidebarNavMode = 'all' | 'by-role' | 'by-unit' | 'favorites' | 'search' | 'preferences';
27101
27188
 
27102
27189
  /** A module containing multiple views */
27103
- export declare interface SidebarNavModule {
27190
+ export declare interface SidebarNavModule extends SidebarNavBranchColors {
27104
27191
  id: string;
27105
27192
  label: string;
27106
27193
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27111,8 +27198,29 @@ export declare interface SidebarNavModule {
27111
27198
  sourceId?: string;
27112
27199
  }
27113
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
+
27114
27222
  /** A role grouping modules */
27115
- export declare interface SidebarNavRole {
27223
+ export declare interface SidebarNavRole extends SidebarNavBranchColors {
27116
27224
  id: string;
27117
27225
  label: string;
27118
27226
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27123,8 +27231,11 @@ export declare interface SidebarNavRole {
27123
27231
  sourceId?: string;
27124
27232
  }
27125
27233
 
27234
+ /** The three trees of a data node: `modules` (the "All" mode), `roles`, `units`. */
27235
+ export declare type SidebarNavTreeName = 'modules' | 'roles' | 'units';
27236
+
27126
27237
  /** An organizational unit grouping modules */
27127
- export declare interface SidebarNavUnit {
27238
+ export declare interface SidebarNavUnit extends SidebarNavBranchColors {
27128
27239
  id: string;
27129
27240
  label: string;
27130
27241
  /** Custom hover tooltip. Falls back to `label` when omitted. */
@@ -27152,8 +27263,8 @@ export declare interface SidebarNavUserPrefs {
27152
27263
  hiddenItems: SidebarNavHiddenItem[];
27153
27264
  favorites: SidebarNavFavorite[];
27154
27265
  /**
27155
- * How many levels to show per mode.
27156
- * 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).
27157
27268
  */
27158
27269
  maxDepth: Partial<Record<SidebarNavMode, number>>;
27159
27270
  /** IDs that are manually collapsed */
@@ -27178,20 +27289,48 @@ export declare interface SidebarNavUserPrefs {
27178
27289
  itemOrder: Partial<Record<SidebarNavMode, string[]>>;
27179
27290
  }
27180
27291
 
27181
- /** A single navigable view / entity view */
27182
- 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 {
27183
27298
  id: string;
27184
27299
  label: string;
27185
27300
  /** Custom hover tooltip. Falls back to `label` when omitted. */
27186
27301
  tooltip?: ReactNode;
27187
27302
  icon?: ReactNode;
27188
- /** 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
+ */
27189
27307
  route?: string;
27190
27308
  /** Badge counter (unread notifications, pending tasks, …) */
27191
27309
  badge?: string | number;
27192
27310
  isExternal?: boolean;
27193
27311
  /** Module this view belongs to */
27194
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;
27195
27334
  }
27196
27335
 
27197
27336
  /**
@@ -28067,17 +28206,20 @@ export { themePastelSky }
28067
28206
 
28068
28207
  export { themePink }
28069
28208
 
28070
- /** Colours used to render a theme preview thumbnail. All optional except `background`. */
28209
+ /** Colours used to render a theme preview thumbnail. */
28071
28210
  export declare interface ThemePreviewColors {
28072
- /** Main page background. */
28211
+ /** Main surface (a theme's `backgrounds.primary`) — the card in the middle of the 'page' shape. */
28073
28212
  background: string;
28074
- /** Sidebar / secondary surface (left bar in 'page' shape). */
28213
+ /**
28214
+ * Secondary surface (`backgrounds.secondary`) — the page background left and right of the card
28215
+ * in the 'page' shape. Defaults to `background`.
28216
+ */
28075
28217
  backgroundSecondary?: string;
28076
- /** Accent / header bar colour. */
28218
+ /** Accent — the bar across the top of the 'page' shape. */
28077
28219
  primary: string;
28078
- /** Body text colour (rendered as a thin line). */
28220
+ /** Body text — the two lines on the card. */
28079
28221
  textColor: string;
28080
- /** Optional border (defaults to a translucent overlay). */
28222
+ /** Border of the thumbnail and of the card (defaults to a translucent overlay). */
28081
28223
  border?: string;
28082
28224
  }
28083
28225
 
@@ -30080,6 +30222,21 @@ declare interface WaitCondition {
30080
30222
  timeout?: number;
30081
30223
  }
30082
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
+
30083
30240
  /** Watermark settings */
30084
30241
  export declare interface WatermarkSettings {
30085
30242
  enabled: boolean;