@gopherium/godmin 0.24.0 → 0.26.0

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/README.md CHANGED
@@ -52,15 +52,40 @@ two lines do for you.
52
52
 
53
53
  | Entry point | Contents |
54
54
  | --- | --- |
55
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `RAIL_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
55
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
56
56
  | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
57
57
  | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
58
58
  | `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |
59
- | `@gopherium/godmin/router` | `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, the `canvas` route static data |
59
+ | `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `routerDefaults`, the `canvas`, `Sidebar` and `capability` route static data |
60
60
  | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
61
61
  | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
62
62
  | `@gopherium/godmin/stylelint` | The design system stylelint rules |
63
63
 
64
+ ## Translations
65
+
66
+ GodMin speaks a few words of its own: Back on a sidebar screen, the name of
67
+ the sidebar column and its phone drawer, and the phone menu button and the
68
+ drawer's close button, which only a screen reader meets. It
69
+ translates them in the WordPress `default` text domain, as `@wordpress/ui`
70
+ translates its own, so `@wordpress/i18n` is a required peer. Every app
71
+ already has it, since
72
+ `@wordpress/ui` depends on it.
73
+
74
+ `listChromeCatalogFor` returns the catalogue GodMin ships for a language,
75
+ Spanish and French today. Both hold these words and the list dates, and the
76
+ Spanish one also holds the list chrome. Load it into `LIST_CHROME_DOMAIN`, the
77
+ `default` domain:
78
+
79
+ ```ts
80
+ import { setLocaleData } from '@wordpress/i18n'
81
+ import { LIST_CHROME_DOMAIN, listChromeCatalogFor } from '@gopherium/godmin'
82
+
83
+ const catalogue = await listChromeCatalogFor('es-ES')
84
+ if (catalogue !== undefined) {
85
+ setLocaleData(catalogue, LIST_CHROME_DOMAIN)
86
+ }
87
+ ```
88
+
64
89
  ## Before your first build
65
90
 
66
91
  Duplicate packages break the application, and nothing points at the cause.
package/dist/base.css CHANGED
@@ -85,7 +85,6 @@ body {
85
85
 
86
86
  .godmin-page__list .dataviews-view-table tbody .dataviews-view-table__primary-column-content > .dataviews-title-field {
87
87
  min-block-size: 0;
88
- font-weight: var(--wpds-typography-font-weight-default);
89
88
  line-height: var(--wpds-typography-line-height-sm);
90
89
  }
91
90
 
@@ -100,8 +99,10 @@ body {
100
99
 
101
100
  @layer godmin {
102
101
  :root {
103
- --godmin-rail-width: 300px;
102
+ --godmin-nav-sidebar-width: 300px;
104
103
  --godmin-canvas-margin: 16px;
104
+ --godmin-navigation-slide-distance: 50px;
105
+ --godmin-navigation-slide-duration: 140ms;
105
106
  }
106
107
 
107
108
  .godmin-layout {
@@ -116,14 +117,14 @@ body {
116
117
  flex-direction: column;
117
118
  }
118
119
 
119
- .godmin-layout__rail {
120
+ .godmin-layout__sidebar {
121
+ z-index: 1;
120
122
  display: flex;
121
123
  flex-direction: column;
122
124
  flex-shrink: 0;
123
- width: var(--godmin-rail-width);
124
- padding: 16px;
125
+ width: var(--godmin-nav-sidebar-width);
126
+ padding: 0;
125
127
  box-sizing: border-box;
126
- overflow-y: auto;
127
128
  }
128
129
 
129
130
  .godmin-layout__topbar {
@@ -138,10 +139,14 @@ body {
138
139
  .godmin-layout__menu {
139
140
  display: flex;
140
141
  flex: none;
142
+ align-items: center;
143
+ justify-content: center;
144
+ inline-size: 52px;
145
+ block-size: 46px;
141
146
  padding: 0;
142
147
  border: 0;
143
148
  background: none;
144
- color: color-mix(in srgb, var(--wpds-color-foreground-content-neutral) 60%, transparent);
149
+ color: var(--wpds-color-foreground-content-neutral);
145
150
  cursor: var(--wpds-cursor-control);
146
151
  }
147
152
 
@@ -156,25 +161,61 @@ body {
156
161
  }
157
162
 
158
163
  .godmin-layout__drawer {
164
+ top: 0;
159
165
  display: flex;
160
166
  flex-direction: column;
161
- padding: 16px;
167
+ width: var(--godmin-nav-sidebar-width);
168
+ max-width: 85vw;
169
+ padding: 0;
162
170
  box-sizing: border-box;
171
+ border: 0;
172
+ border-radius: 0;
173
+ background: var(--wpds-color-background-surface-neutral-weak);
174
+ box-shadow: 2px 0 8px rgba(0, 0, 0, 0.2);
175
+ }
176
+
177
+ [role='presentation']:has(+ * > .godmin-layout__drawer) {
178
+ --backdrop-opacity: 0.5;
179
+ background-color: #000;
180
+ cursor: var(--wpds-cursor-control);
181
+ }
182
+
183
+ .godmin-sidebar__content {
184
+ flex: 1 1 0;
185
+ min-height: 0;
186
+ overflow-x: hidden;
163
187
  overflow-y: auto;
188
+ contain: content;
189
+ }
190
+
191
+ .godmin-sidebar__footer {
192
+ display: flex;
193
+ flex-direction: column;
194
+ flex-shrink: 0;
195
+ gap: 8px;
196
+ padding: 16px;
197
+ border-top: 1px solid var(--wpds-color-stroke-surface-neutral);
198
+ }
199
+
200
+ .godmin-sidebar__footer-note {
201
+ color: var(--wpds-color-foreground-content-neutral-weak);
202
+ font-size: var(--wpds-typography-font-size-sm);
203
+ line-height: var(--wpds-typography-line-height-xs);
164
204
  }
165
205
 
166
206
  .godmin-menu-count__badge {
167
207
  --godmin-menu-count-size: 18px;
168
208
  display: inline-block;
169
- vertical-align: top;
209
+ vertical-align: middle;
170
210
  box-sizing: border-box;
171
211
  min-inline-size: var(--godmin-menu-count-size);
172
212
  block-size: var(--godmin-menu-count-size);
173
- margin-block: 1px -1px;
174
213
  margin-inline-start: 2px;
175
214
  padding-block: 0;
176
215
  padding-inline: 5px;
177
216
  border-radius: calc(var(--godmin-menu-count-size) / 2);
217
+ background-color: var(--wpds-color-background-thumb-brand);
218
+ color: var(--wpds-color-foreground-interactive-neutral-strong);
178
219
  font-size: var(--wpds-typography-font-size-xs);
179
220
  font-weight: inherit;
180
221
  line-height: 1.6;
@@ -206,7 +247,7 @@ body {
206
247
  overflow: hidden;
207
248
  }
208
249
 
209
- .godmin-layout:has(> .godmin-layout__rail) .godmin-layout__canvas {
250
+ .godmin-layout:has(> .godmin-layout__sidebar) .godmin-layout__canvas {
210
251
  margin-inline-start: 0;
211
252
  }
212
253
 
@@ -249,8 +290,8 @@ body {
249
290
  pointer-events: none;
250
291
  }
251
292
 
252
- :root:has(.godmin-layout__rail) .godmin-toasts {
253
- inset-inline-start: var(--godmin-rail-width);
293
+ :root:has(.godmin-layout__sidebar) .godmin-toasts {
294
+ inset-inline-start: var(--godmin-nav-sidebar-width);
254
295
  inset-inline-end: var(--godmin-canvas-margin);
255
296
  }
256
297
 
@@ -338,28 +379,247 @@ body {
338
379
  text-decoration: none;
339
380
  }
340
381
 
341
- .godmin-nav-screen__title {
342
- flex: 1;
343
- min-width: 0;
382
+ .godmin-navigation {
383
+ display: flex;
384
+ flex-direction: column;
385
+ height: 100%;
344
386
  }
345
387
 
346
- .godmin-nav-screen__title:focus {
347
- outline: none;
388
+ .godmin-navigation__screen-wrapper {
389
+ display: flex;
390
+ flex-direction: column;
391
+ height: 100%;
392
+ max-height: 100%;
393
+ padding: 0 12px;
394
+ overflow-x: auto;
395
+ scrollbar-width: thin;
396
+ scrollbar-gutter: stable;
397
+ scrollbar-color: transparent transparent;
398
+ animation-duration: var(--godmin-navigation-slide-duration);
399
+ animation-timing-function: ease-in-out;
400
+ will-change: transform, opacity;
401
+ }
402
+
403
+ .godmin-navigation__screen-wrapper:is(:hover, :focus, :focus-within) {
404
+ scrollbar-color: var(--wpds-color-stroke-surface-neutral-strong) transparent;
405
+ }
406
+
407
+ .godmin-navigation__screen-wrapper::-webkit-scrollbar {
408
+ width: 12px;
409
+ height: 12px;
410
+ }
411
+
412
+ .godmin-navigation__screen-wrapper::-webkit-scrollbar-track {
413
+ background-color: transparent;
414
+ }
415
+
416
+ .godmin-navigation__screen-wrapper::-webkit-scrollbar-thumb {
417
+ border: 3px solid transparent;
418
+ border-radius: 8px;
419
+ background-color: transparent;
420
+ background-clip: padding-box;
421
+ }
422
+
423
+ .godmin-navigation__screen-wrapper:hover::-webkit-scrollbar-thumb,
424
+ .godmin-navigation__screen-wrapper:focus::-webkit-scrollbar-thumb,
425
+ .godmin-navigation__screen-wrapper:focus-within::-webkit-scrollbar-thumb {
426
+ background-color: var(--wpds-color-stroke-surface-neutral-strong);
427
+ }
428
+
429
+ @media (hover: none) {
430
+ .godmin-navigation__screen-wrapper {
431
+ scrollbar-color: var(--wpds-color-stroke-surface-neutral-strong) transparent;
432
+ }
433
+ }
434
+
435
+ .godmin-navigation__screen-wrapper--forward {
436
+ animation-name: godmin-slide-from-end;
437
+ }
438
+
439
+ .godmin-navigation__screen-wrapper--backward {
440
+ animation-name: godmin-slide-from-start;
441
+ }
442
+
443
+ .godmin-navigation__screen-wrapper--forward:dir(rtl) {
444
+ animation-name: godmin-slide-from-start;
445
+ }
446
+
447
+ .godmin-navigation__screen-wrapper--backward:dir(rtl) {
448
+ animation-name: godmin-slide-from-end;
449
+ }
450
+
451
+ @keyframes godmin-slide-from-end {
452
+ 0% {
453
+ opacity: 0;
454
+ transform: translateX(var(--godmin-navigation-slide-distance));
455
+ }
456
+
457
+ 100% {
458
+ opacity: 1;
459
+ transform: none;
460
+ }
461
+ }
462
+
463
+ @keyframes godmin-slide-from-start {
464
+ 0% {
465
+ opacity: 0;
466
+ transform: translateX(calc(-1 * var(--godmin-navigation-slide-distance)));
467
+ }
468
+
469
+ 100% {
470
+ opacity: 1;
471
+ transform: none;
472
+ }
473
+ }
474
+
475
+ .godmin-navigation-screen {
476
+ display: flex;
477
+ flex-direction: column;
478
+ flex-grow: 1;
479
+ }
480
+
481
+ .godmin-navigation-screen__main {
482
+ flex-grow: 1;
483
+ margin-bottom: 16px;
484
+ }
485
+
486
+ .godmin-navigation-screen__main--has-footer {
487
+ margin-bottom: 0;
348
488
  }
349
489
 
350
- .godmin-nav-screen__back {
490
+ .godmin-navigation-screen__title-icon {
491
+ position: sticky;
492
+ top: 0;
493
+ z-index: 1;
494
+ display: flex;
495
+ align-items: flex-start;
496
+ gap: 12px;
497
+ margin-bottom: 8px;
498
+ padding-top: 32px;
499
+ padding-bottom: 8px;
500
+ background: var(--wpds-color-background-surface-neutral-weak);
501
+ }
502
+
503
+ .godmin-navigation-screen__title-icon--root {
504
+ padding-inline-start: 44px;
505
+ }
506
+
507
+ .godmin-navigation-screen__back {
351
508
  display: inline-flex;
352
- color: inherit;
353
- border-radius: var(--wpds-border-radius-md);
509
+ flex-shrink: 0;
510
+ align-items: center;
511
+ justify-content: center;
512
+ inline-size: 32px;
513
+ block-size: 32px;
514
+ border-radius: var(--wpds-border-radius-sm);
515
+ color: var(--wpds-color-foreground-interactive-neutral);
516
+ }
517
+
518
+ .godmin-navigation-screen__back:is(:hover, :focus) {
519
+ color: var(--wpds-color-foreground-interactive-neutral-active);
354
520
  }
355
521
 
356
- .godmin-nav-screen__back:focus-visible {
522
+ .godmin-navigation-screen__back:focus-visible {
357
523
  outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
358
- outline-offset: 2px;
524
+ outline-offset: var(--wpds-border-width-focus);
359
525
  }
360
526
 
361
- .godmin-nav-screen__description {
362
- color: var(--wpds-color-foreground-content-neutral-weak);
527
+ .godmin-navigation-screen__back:focus:not(:focus-visible) {
528
+ outline: none;
529
+ }
530
+
531
+ .godmin-navigation-screen__title {
532
+ flex-grow: 1;
533
+ min-width: 0;
534
+ margin: 0;
535
+ color: var(--wpds-color-foreground-content-neutral);
536
+ font-size: var(--wpds-typography-font-size-xl);
537
+ font-weight: var(--wpds-typography-font-weight-emphasis);
538
+ line-height: var(--wpds-typography-line-height-xl);
539
+ overflow-wrap: break-word;
540
+ }
541
+
542
+ .godmin-navigation-screen__actions {
543
+ display: flex;
544
+ flex-shrink: 0;
545
+ }
546
+
547
+ .godmin-navigation-screen__content {
548
+ padding: 0 16px;
549
+ color: var(--wpds-color-foreground-content-neutral);
550
+ }
551
+
552
+ .godmin-navigation-screen__description {
553
+ margin: 0 0 32px;
554
+ color: var(--wpds-color-foreground-content-neutral);
555
+ }
556
+
557
+ .godmin-navigation-screen__footer {
558
+ position: sticky;
559
+ bottom: 0;
560
+ margin-top: 16px;
561
+ padding: 8px 16px;
562
+ border-top: 1px solid var(--wpds-color-stroke-surface-neutral);
563
+ background: var(--wpds-color-background-surface-neutral-weak);
564
+ }
565
+
566
+ .godmin-navigation-list {
567
+ margin-block: 0;
568
+ margin-inline: -16px;
569
+ padding: 0;
570
+ list-style: none;
571
+ }
572
+
573
+ .godmin-navigation-item {
574
+ display: flex;
575
+ align-items: center;
576
+ gap: var(--wpds-dimension-gap-sm);
577
+ box-sizing: border-box;
578
+ min-height: 40px;
579
+ padding: calc((36px - 13px * 1.4 - 2px) / 2) 12px;
580
+ border: 1px solid transparent;
581
+ border-radius: var(--wpds-border-radius-sm);
582
+ color: var(--wpds-color-foreground-interactive-neutral-weak);
583
+ font-size: var(--wpds-typography-font-size-md);
584
+ font-weight: var(--wpds-typography-font-weight-default);
585
+ line-height: normal;
586
+ text-decoration: none;
587
+ }
588
+
589
+ .godmin-navigation-item--with-suffix {
590
+ padding-inline-end: 16px;
591
+ }
592
+
593
+ .godmin-navigation-item:is(:hover, :focus) {
594
+ color: var(--wpds-color-foreground-interactive-neutral-weak-active);
595
+ }
596
+
597
+ .godmin-navigation-item[aria-current='page'] {
598
+ background: var(--wpds-color-background-interactive-neutral-weak-active);
599
+ color: var(--wpds-color-foreground-interactive-neutral-weak-active);
600
+ font-weight: var(--wpds-typography-font-weight-emphasis);
601
+ }
602
+
603
+ .godmin-navigation-item:focus-visible {
604
+ outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
605
+ outline-offset: var(--wpds-border-width-focus);
606
+ transform: translateZ(0);
607
+ }
608
+
609
+ .godmin-navigation-item__icon,
610
+ .godmin-navigation-item__drilldown-indicator {
611
+ flex: none;
612
+ inline-size: 24px;
613
+ block-size: 24px;
614
+ }
615
+
616
+ .godmin-navigation-item__label {
617
+ flex: 1;
618
+ min-width: 0;
619
+ }
620
+
621
+ .godmin-navigation-item__suffix {
622
+ flex: none;
363
623
  }
364
624
 
365
625
  .godmin-page__head {
@@ -464,6 +724,9 @@ body {
464
724
  display: flex;
465
725
  position: relative;
466
726
  gap: var(--wpds-dimension-gap-lg);
727
+ margin: 0;
728
+ padding: 0;
729
+ list-style: none;
467
730
  overflow-x: auto;
468
731
  overscroll-behavior-inline: none;
469
732
  }
@@ -640,10 +903,6 @@ body {
640
903
  color: var(--wpds-color-foreground-content-neutral);
641
904
  }
642
905
 
643
- .godmin-page__list .godmin-table__title {
644
- font-weight: var(--wpds-typography-font-weight-default);
645
- }
646
-
647
906
  .godmin-table__title a {
648
907
  color: var(--wpds-color-foreground-interactive-neutral);
649
908
  text-decoration: none;
@@ -739,6 +998,10 @@ body {
739
998
  .godmin-toast {
740
999
  animation-duration: 1ms;
741
1000
  }
1001
+
1002
+ .godmin-navigation__screen-wrapper {
1003
+ animation-duration: 0s;
1004
+ }
742
1005
  }
743
1006
 
744
1007
  .godmin-loading-screen {
@@ -1,7 +1,11 @@
1
1
  /**
2
- * The viewport width below which the rail becomes a drawer.
2
+ * The viewport width from which a screen counts as huge, the WordPress huge breakpoint.
3
3
  */
4
- export declare const RAIL_BREAKPOINT = 1024;
4
+ export declare const HUGE_BREAKPOINT = 1440;
5
+ /**
6
+ * The viewport width below which the sidebar becomes a drawer.
7
+ */
8
+ export declare const SIDEBAR_BREAKPOINT = 1024;
5
9
  /**
6
10
  * The viewport width below which the canvas meets the screen edges, the WordPress medium breakpoint.
7
11
  */
@@ -19,6 +23,6 @@ export declare const SHEET_BREAKPOINT = 600;
19
23
  */
20
24
  export declare const TITLE_BREAKPOINT = 404;
21
25
  /**
22
- * The media query the frame folds its rail at.
26
+ * The media query the frame folds its sidebar at.
23
27
  */
24
28
  export declare const SMALL_VIEWPORT = "(max-width: 1023px)";
@@ -1,7 +1,11 @@
1
1
  /**
2
- * The viewport width below which the rail becomes a drawer.
2
+ * The viewport width from which a screen counts as huge, the WordPress huge breakpoint.
3
3
  */
4
- export const RAIL_BREAKPOINT = 1024;
4
+ export const HUGE_BREAKPOINT = 1440;
5
+ /**
6
+ * The viewport width below which the sidebar becomes a drawer.
7
+ */
8
+ export const SIDEBAR_BREAKPOINT = 1024;
5
9
  /**
6
10
  * The viewport width below which the canvas meets the screen edges, the WordPress medium breakpoint.
7
11
  */
@@ -19,6 +23,6 @@ export const SHEET_BREAKPOINT = 600;
19
23
  */
20
24
  export const TITLE_BREAKPOINT = 404;
21
25
  /**
22
- * The media query the frame folds its rail at.
26
+ * The media query the frame folds its sidebar at.
23
27
  */
24
- export const SMALL_VIEWPORT = `(max-width: ${RAIL_BREAKPOINT - 1}px)`;
28
+ export const SMALL_VIEWPORT = `(max-width: ${SIDEBAR_BREAKPOINT - 1}px)`;
@@ -0,0 +1,19 @@
1
+ import type { AnyRouter, LinkComponentProps, RegisteredRouter } from '@tanstack/react-router';
2
+ import type { ReactElement, ReactNode } from 'react';
3
+ /** A row whose address opens a route that declares a Sidebar. Draws the chevron. Sits inside a NavigationList. */
4
+ export type DrilldownItemProps<TRouter extends AnyRouter = RegisteredRouter, TFrom extends string = string, TTo extends string | undefined = undefined, TMaskFrom extends string = TFrom, TMaskTo extends string = ''> = LinkComponentProps<'a', TRouter, TFrom, TTo, TMaskFrom, TMaskTo> & {
5
+ /** None, since the row takes its id from its address. */
6
+ id?: never;
7
+ /** A glyph from `@wordpress/icons`, drawn at 24px. */
8
+ icon?: ReactElement;
9
+ /** Drawn before the chevron, such as a MenuCount. */
10
+ suffix?: ReactNode;
11
+ children: ReactNode;
12
+ };
13
+ /**
14
+ * Renders a sidebar row that opens a sub menu: its icon, label, suffix and chevron, with an id taken from its address.
15
+ * A plain click inside a frame records a forward move from this row to its address.
16
+ * @param props - The TanStack Link props, the icon, the suffix and the label.
17
+ * @returns The row element, or null when its address opens a route the reader may not open.
18
+ */
19
+ export declare function DrilldownItem<TRouter extends AnyRouter = RegisteredRouter, const TFrom extends string = string, const TTo extends string | undefined = undefined, const TMaskFrom extends string = TFrom, const TMaskTo extends string = ''>({ icon, suffix, children, ...link }: DrilldownItemProps<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): import("react").JSX.Element;
@@ -0,0 +1,31 @@
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { useRouter } from '@tanstack/react-router';
4
+ import { isRTL } from '@wordpress/i18n';
5
+ import { Icon, chevronLeftSmall, chevronRightSmall } from '@wordpress/icons';
6
+ import { useContext } from 'react';
7
+ import { ROW_CLASS, Row, RowSuffix } from './navigation-item.js';
8
+ import { NavigationStateContext, isPlainClick, recordDrilldown } from './navigation-state.js';
9
+ import { findMoveTarget, findRowRoutes } from './path-matching.js';
10
+ /** The start of the id a drilldown row takes from its address. */
11
+ const ID_PREFIX = 'godmin-drilldown-item-';
12
+ /**
13
+ * Renders a sidebar row that opens a sub menu: its icon, label, suffix and chevron, with an id taken from its address.
14
+ * A plain click inside a frame records a forward move from this row to its address.
15
+ * @param props - The TanStack Link props, the icon, the suffix and the label.
16
+ * @returns The row element, or null when its address opens a route the reader may not open.
17
+ */
18
+ export function DrilldownItem({ icon, suffix, children, ...link }) {
19
+ const router = useRouter();
20
+ const state = useContext(NavigationStateContext);
21
+ const address = link;
22
+ const routes = findRowRoutes(router, address);
23
+ const id = ID_PREFIX + routes.href;
24
+ const onClick = (event) => {
25
+ address.onClick?.(event);
26
+ if (state !== undefined && isPlainClick(event)) {
27
+ recordDrilldown(state, id, findMoveTarget(router, address));
28
+ }
29
+ };
30
+ return (_jsx(Row, { link: { ...address, onClick }, routes: routes, icon: icon, className: ROW_CLASS, id: id, end: _jsxs(_Fragment, { children: [suffix === undefined ? null : _jsx(RowSuffix, { children: suffix }), _jsx(Icon, { icon: isRTL() ? chevronLeftSmall : chevronRightSmall, size: 24, className: "godmin-navigation-item__drilldown-indicator" })] }), children: children }));
31
+ }
package/dist/frame.d.ts CHANGED
@@ -10,23 +10,31 @@ export interface FrameRootProps {
10
10
  canvasColor?: ThemeColor;
11
11
  }
12
12
  /**
13
- * Frames an admin application, folding its rail away on a narrow viewport.
13
+ * Frames an admin application, folding its sidebar away on a narrow viewport,
14
+ * and holds the moves its sidebar parts share.
14
15
  * @param props - The regions, the current location, and the region colors.
15
16
  * @returns The frame element.
16
17
  */
17
18
  declare function Root({ children, location, chromeColor, canvasColor }: FrameRootProps): import("react").JSX.Element;
18
- export interface FrameRailProps {
19
+ export interface FrameSidebarProps {
19
20
  children: ReactNode;
20
21
  brand?: ReactNode;
22
+ /** The name of the menu button, godmin's translated "Open navigation panel" when absent. */
21
23
  menuLabel?: string;
24
+ /** The name of the region the column is, godmin's translated "Navigation" when absent. */
25
+ label?: string;
26
+ /** What sits under the menu and never moves, such as the account panel. */
27
+ footer?: ReactNode;
28
+ /** One short line of small grey text under the footer, such as the version. */
29
+ footerNote?: ReactNode;
22
30
  }
23
31
  /**
24
- * Renders the navigation region, as a rail when there is room and as a top bar
25
- * with a drawer when there is not.
26
- * @param props - The rail content, the brand, and the menu button label.
27
- * @returns The rail element.
32
+ * Renders the navigation region, as a sidebar when there is room and as a top bar
33
+ * with a drawer when there is not, its content above its footer in both.
34
+ * @param props - The sidebar content, the brand, the menu button label, the region name, the footer and its note.
35
+ * @returns The sidebar element.
28
36
  */
29
- declare function Rail({ children, brand, menuLabel }: FrameRailProps): import("react").JSX.Element;
37
+ declare function Sidebar({ children, brand, menuLabel, label, footer, footerNote, }: FrameSidebarProps): import("react").JSX.Element;
30
38
  /**
31
39
  * How a screen fills its canvas region.
32
40
  */
@@ -48,7 +56,7 @@ declare function Canvas({ children, canvas, notices }: FrameCanvasProps): import
48
56
  */
49
57
  export declare const Frame: {
50
58
  Root: typeof Root;
51
- Rail: typeof Rail;
59
+ Sidebar: typeof Sidebar;
52
60
  Canvas: typeof Canvas;
53
61
  };
54
62
  export {};