@gopherium/godmin 0.23.1 → 0.25.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.
Files changed (43) hide show
  1. package/README.md +27 -2
  2. package/dist/base.css +332 -27
  3. package/dist/breakpoints.d.ts +7 -3
  4. package/dist/breakpoints.js +8 -4
  5. package/dist/drilldown-item.d.ts +17 -0
  6. package/dist/drilldown-item.js +31 -0
  7. package/dist/frame.d.ts +21 -11
  8. package/dist/frame.js +69 -28
  9. package/dist/index.d.ts +6 -4
  10. package/dist/index.js +3 -2
  11. package/dist/list-chrome/es-ES.d.ts +1 -1
  12. package/dist/list-chrome/es-ES.js +5 -1
  13. package/dist/list-chrome/fr-FR.d.ts +1 -1
  14. package/dist/list-chrome/fr-FR.js +5 -1
  15. package/dist/list-chrome.d.ts +1 -1
  16. package/dist/list-chrome.js +1 -1
  17. package/dist/list-empty.d.ts +1 -1
  18. package/dist/list-empty.js +4 -2
  19. package/dist/menu-count.d.ts +12 -0
  20. package/dist/menu-count.js +14 -0
  21. package/dist/menu-item.d.ts +29 -0
  22. package/dist/menu-item.js +33 -0
  23. package/dist/navigation-item.d.ts +45 -0
  24. package/dist/navigation-item.js +50 -0
  25. package/dist/navigation-list.d.ts +14 -0
  26. package/dist/navigation-list.js +62 -0
  27. package/dist/navigation-screen.d.ts +24 -0
  28. package/dist/navigation-screen.js +47 -0
  29. package/dist/navigation-state.d.ts +83 -0
  30. package/dist/navigation-state.js +88 -0
  31. package/dist/navigation.d.ts +23 -0
  32. package/dist/navigation.js +133 -0
  33. package/dist/page-tabs.d.ts +5 -4
  34. package/dist/page-tabs.js +12 -3
  35. package/dist/page.d.ts +20 -6
  36. package/dist/page.js +32 -10
  37. package/dist/path-matching.d.ts +68 -0
  38. package/dist/path-matching.js +126 -0
  39. package/dist/router.d.ts +24 -2
  40. package/dist/router.js +16 -3
  41. package/package.json +3 -6
  42. package/dist/nav-screen.d.ts +0 -17
  43. package/dist/nav-screen.js +0 -31
package/dist/frame.js CHANGED
@@ -1,15 +1,14 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
2
  /* oxlint-disable react/only-export-components -- a compound component is an
3
3
  object export standing beside the parts it is built from. */
4
+ import { __ } from '@wordpress/i18n';
5
+ import { Icon, menu } from '@wordpress/icons';
4
6
  import { ThemeProvider } from '@wordpress/theme';
5
7
  import { Drawer, VisuallyHidden } from '@wordpress/ui';
6
- import { createContext, useContext, useEffect, useState } from 'react';
8
+ import { Children, createContext, useContext, useEffect, useState } from 'react';
7
9
  import { SMALL_VIEWPORT } from './breakpoints.js';
10
+ import { NavigationStateContext, createNavigationState, takeDrawerStays } from './navigation-state.js';
8
11
  import { useMediaQuery } from './use-media-query.js';
9
- /**
10
- * The glyph on the button that opens the rail drawer, drawn where the admin bar menu toggle draws its bars.
11
- */
12
- const menuIcon = (_jsx("svg", { xmlns: "http://www.w3.org/2000/svg", width: "52", height: "46", viewBox: "0 0 52 46", fill: "currentColor", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M11 11h28v4H11zm0 10h28v4H11zm0 10h28v4H11z" }) }));
13
12
  /**
14
13
  * The chrome background seeded when an application names none.
15
14
  */
@@ -18,59 +17,101 @@ const CHROME_COLOR = { background: '#26292b' };
18
17
  * The canvas background seeded when an application names none, the design system default background.
19
18
  */
20
19
  const CANVAS_COLOR = { background: '#fcfcfc' };
21
- const FrameContext = createContext({ small: false, location: undefined, layout: null });
20
+ const FrameContext = createContext({
21
+ small: false,
22
+ location: undefined,
23
+ layout: null,
24
+ navigation: createNavigationState(),
25
+ });
22
26
  /**
23
- * Frames an admin application, folding its rail away on a narrow viewport.
27
+ * Frames an admin application, folding its sidebar away on a narrow viewport,
28
+ * and holds the moves its sidebar parts share.
24
29
  * @param props - The regions, the current location, and the region colors.
25
30
  * @returns The frame element.
26
31
  */
27
32
  function Root({ children, location, chromeColor = CHROME_COLOR, canvasColor = CANVAS_COLOR }) {
28
33
  const small = useMediaQuery(SMALL_VIEWPORT);
29
34
  const [layout, setLayout] = useState(null);
35
+ const [navigation] = useState(createNavigationState);
30
36
  const classes = small ? 'godmin-layout godmin-layout--small' : 'godmin-layout';
31
- return (_jsx(ThemeProvider, { color: chromeColor, children: _jsx(FrameContext.Provider, { value: { small, location, layout }, children: _jsx("div", { ref: setLayout, className: classes, children: _jsx(CanvasColorContext.Provider, { value: canvasColor, children: children }) }) }) }));
37
+ return (_jsx(ThemeProvider, { color: chromeColor, children: _jsx(FrameContext.Provider, { value: { small, location, layout, navigation }, children: _jsx(NavigationStateContext.Provider, { value: navigation, children: _jsx("div", { ref: setLayout, className: classes, children: _jsx(CanvasColorContext.Provider, { value: canvasColor, children: children }) }) }) }) }));
32
38
  }
33
39
  const CanvasColorContext = createContext(undefined);
34
40
  /**
35
- * Renders the navigation region, as a rail when there is room and as a top bar
36
- * with a drawer when there is not.
37
- * @param props - The rail content, the brand, and the menu button label.
38
- * @returns The rail element.
41
+ * Renders the sidebar footer: the panel, then the note, or nothing when the app gives neither.
42
+ * @param props - The footer panel and the note.
43
+ * @returns The footer element, or null.
39
44
  */
40
- function Rail({ children, brand, menuLabel = 'Open navigation' }) {
45
+ function SidebarFooter({ footer, footerNote }) {
46
+ if (footer === undefined && footerNote === undefined) {
47
+ return null;
48
+ }
49
+ return (_jsxs("div", { className: "godmin-sidebar__footer", children: [footer, footerNote === undefined ? null : _jsx("div", { className: "godmin-sidebar__footer-note", children: footerNote })] }));
50
+ }
51
+ /**
52
+ * Renders the navigation region, as a sidebar when there is room and as a top bar
53
+ * with a drawer when there is not, its content above its footer in both.
54
+ * @param props - The sidebar content, the brand, the menu button label, the region name, the footer and its note.
55
+ * @returns The sidebar element.
56
+ */
57
+ function Sidebar({ children, brand, menuLabel = __('Open navigation panel'), label = __('Navigation'), footer, footerNote, }) {
41
58
  const { small } = useContext(FrameContext);
59
+ const content = (_jsxs(_Fragment, { children: [_jsx("div", { className: "godmin-sidebar__content", children: children }), _jsx(SidebarFooter, { footer: footer, footerNote: footerNote })] }));
42
60
  if (!small) {
43
- return _jsx("div", { className: "godmin-layout__rail", children: children });
61
+ return (_jsx("div", { className: "godmin-layout__sidebar", role: "region", "aria-label": label, tabIndex: -1, children: content }));
44
62
  }
45
- return (_jsx(TopBar, { brand: brand, menuLabel: menuLabel, children: children }));
63
+ return (_jsx(TopBar, { brand: brand, menuLabel: menuLabel, children: content }));
46
64
  }
47
65
  /**
48
- * Renders the narrow viewport chrome: a menu button opening the rail content in
49
- * a drawer, beside the brand.
50
- * @param props - The rail content, the brand, and the menu button label.
66
+ * Renders the narrow viewport chrome: a menu button opening the sidebar content in
67
+ * a drawer, beside the brand. The drawer closes on a page change, unless a drilldown row or Back made it,
68
+ * and ends in a close button only assistive technology meets, the name of WordPress's phone backdrop.
69
+ * @param props - The sidebar content, the brand, and the menu button label.
51
70
  * @returns The top bar element.
52
71
  */
53
72
  function TopBar({ children, brand, menuLabel, }) {
54
- const { location, layout } = useContext(FrameContext);
73
+ const { location, layout, navigation } = useContext(FrameContext);
55
74
  const [open, setOpen] = useState(false);
56
75
  useEffect(() => {
57
- setOpen(false);
58
- }, [location]);
59
- return (_jsxs("div", { className: "godmin-layout__topbar", children: [_jsxs(Drawer.Root, { open: open, onOpenChange: setOpen, children: [_jsx(Drawer.Trigger, { render: _jsx("button", { type: "button", className: "godmin-layout__menu", "aria-label": menuLabel }), children: menuIcon }), _jsxs(Drawer.Popup, { className: "godmin-layout__drawer", portal: _jsx(Drawer.Portal, { container: layout }), children: [_jsx(VisuallyHidden, { render: _jsx(Drawer.Title, {}), children: menuLabel }), children] })] }), brand] }));
76
+ if (!takeDrawerStays(navigation, location)) {
77
+ setOpen(false);
78
+ }
79
+ }, [location, navigation]);
80
+ return (_jsxs("div", { className: "godmin-layout__topbar", children: [_jsxs(Drawer.Root, { open: open, onOpenChange: setOpen, children: [_jsx(Drawer.Trigger, { render: _jsx("button", { type: "button", className: "godmin-layout__menu", "aria-label": menuLabel }), children: _jsx(Icon, { icon: menu }) }), _jsxs(Drawer.Popup, { className: "godmin-layout__drawer", portal: _jsx(Drawer.Portal, { container: layout }), children: [_jsx(VisuallyHidden, { render: _jsx(Drawer.Title, {}), children: __('Navigation') }), children, _jsx(VisuallyHidden, { render: _jsx(Drawer.Action, { variant: "unstyled", tabIndex: -1 }), children: __('Close navigation panel') })] })] }), brand] }));
81
+ }
82
+ /**
83
+ * Tells whether notices hold anything React draws.
84
+ * @param notices - The notices the app gives.
85
+ * @returns Whether any of them is something other than nothing or an empty string.
86
+ */
87
+ function hasNotices(notices) {
88
+ return Children.toArray(notices).some((notice) => notice !== '');
89
+ }
90
+ /**
91
+ * Renders the notices in a band of their own, with square corners on a bleed canvas, or nothing when there are none.
92
+ * @param props - The notices and how the screen fills the canvas.
93
+ * @returns The band element, or null.
94
+ */
95
+ function Notices({ notices, canvas }) {
96
+ if (!hasNotices(notices)) {
97
+ return null;
98
+ }
99
+ const band = _jsx("div", { className: "godmin-layout__notices", children: notices });
100
+ return canvas === 'bleed' ? _jsx(ThemeProvider, { cornerRadius: "none", children: band }) : band;
60
101
  }
61
102
  /**
62
- * Renders the region showing the active screen.
63
- * @param props - The screen, and whether it fills the canvas edge to edge.
103
+ * Renders the region showing the active screen, under a band of notices when the app gives some.
104
+ * @param props - The screen, whether it fills the canvas edge to edge, and the notices.
64
105
  * @returns The canvas element.
65
106
  */
66
- function Canvas({ children, canvas = 'padded' }) {
107
+ function Canvas({ children, canvas = 'padded', notices }) {
67
108
  const color = useContext(CanvasColorContext);
68
109
  const classes = canvas === 'bleed'
69
110
  ? 'godmin-layout__canvas godmin-layout__canvas--bleed'
70
111
  : 'godmin-layout__canvas';
71
- return (_jsx(ThemeProvider, { color: color, children: _jsx("main", { className: classes, style: { isolation: 'isolate' }, children: children }) }));
112
+ return (_jsx(ThemeProvider, { color: color, children: _jsxs("main", { className: classes, style: { isolation: 'isolate' }, children: [_jsx(Notices, { notices: notices, canvas: canvas }), children] }) }));
72
113
  }
73
114
  /**
74
115
  * The admin frame, whose regions are present when their element is rendered.
75
116
  */
76
- export const Frame = { Root, Rail, Canvas };
117
+ export const Frame = { Root, Sidebar, Canvas };
package/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@ export { AdminRoot } from './admin-root.js';
2
2
  export type { AdminRootProps } from './admin-root.js';
3
3
  export { InitialsAvatar } from './avatar.js';
4
4
  export type { InitialsAvatarProps } from './avatar.js';
5
- export { DENSE_BREAKPOINT, EDGE_BREAKPOINT, RAIL_BREAKPOINT, SHEET_BREAKPOINT, SMALL_VIEWPORT, TITLE_BREAKPOINT, } from './breakpoints.js';
5
+ export { DENSE_BREAKPOINT, EDGE_BREAKPOINT, HUGE_BREAKPOINT, SHEET_BREAKPOINT, SIDEBAR_BREAKPOINT, SMALL_VIEWPORT, TITLE_BREAKPOINT, } from './breakpoints.js';
6
6
  export { useBulkRun } from './bulk-run.js';
7
7
  export type { BulkRun } from './bulk-run.js';
8
8
  export { bulkNotes, runEach } from './bulk.js';
@@ -14,7 +14,7 @@ export type { FileButtonProps } from './file-button.js';
14
14
  export { FormBody } from './form.js';
15
15
  export type { FormBodyProps, FormKind } from './form.js';
16
16
  export { Frame } from './frame.js';
17
- export type { CanvasMode, FrameCanvasProps, FrameRailProps, FrameRootProps, } from './frame.js';
17
+ export type { CanvasMode, FrameCanvasProps, FrameRootProps, FrameSidebarProps, } from './frame.js';
18
18
  export { keyFromLabel } from './keys.js';
19
19
  export type { KeyOptions, KeyStyle } from './keys.js';
20
20
  export { LIST_CHROME_DOMAIN, listChromeCatalogFor } from './list-chrome.js';
@@ -26,8 +26,10 @@ export type { ListRun, ListRunState, RunSettled } from './list-run.js';
26
26
  export { LoadingRows, LoadingScreen } from './loading.js';
27
27
  export { LogItem, LogList, LogTime } from './log-list.js';
28
28
  export type { LogItemProps, LogListProps, LogTimeProps } from './log-list.js';
29
- export { NavScreen } from './nav-screen.js';
30
- export type { NavScreenProps } from './nav-screen.js';
29
+ export { MenuCount } from './menu-count.js';
30
+ export type { MenuCountProps } from './menu-count.js';
31
+ export { NavigationScreen } from './navigation-screen.js';
32
+ export type { NavigationScreenProps } from './navigation-screen.js';
31
33
  export { ErrorNotice, LoadMore, Page, PageTitle, SectionTitle } from './page.js';
32
34
  export type { LoadMoreQuery, PageProps } from './page.js';
33
35
  export { PageTab, PageTabs } from './page-tabs.js';
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  export { AdminRoot } from './admin-root.js';
3
3
  export { InitialsAvatar } from './avatar.js';
4
- export { DENSE_BREAKPOINT, EDGE_BREAKPOINT, RAIL_BREAKPOINT, SHEET_BREAKPOINT, SMALL_VIEWPORT, TITLE_BREAKPOINT, } from './breakpoints.js';
4
+ export { DENSE_BREAKPOINT, EDGE_BREAKPOINT, HUGE_BREAKPOINT, SHEET_BREAKPOINT, SIDEBAR_BREAKPOINT, SMALL_VIEWPORT, TITLE_BREAKPOINT, } from './breakpoints.js';
5
5
  export { useBulkRun } from './bulk-run.js';
6
6
  export { bulkNotes, runEach } from './bulk.js';
7
7
  export { ConfirmBody } from './confirm.js';
@@ -14,7 +14,8 @@ export { ListEmpty } from './list-empty.js';
14
14
  export { useListRun } from './list-run.js';
15
15
  export { LoadingRows, LoadingScreen } from './loading.js';
16
16
  export { LogItem, LogList, LogTime } from './log-list.js';
17
- export { NavScreen } from './nav-screen.js';
17
+ export { MenuCount } from './menu-count.js';
18
+ export { NavigationScreen } from './navigation-screen.js';
18
19
  export { ErrorNotice, LoadMore, Page, PageTitle, SectionTitle } from './page.js';
19
20
  export { PageTab, PageTabs } from './page-tabs.js';
20
21
  export { RenameBody } from './rename.js';
@@ -1,4 +1,4 @@
1
1
  import type { ListChromeCatalog } from '../list-chrome.js';
2
- /** The Spanish list chrome and list dates, compiled from the es-ES.po source beside it. */
2
+ /** The Spanish list chrome, list dates and sidebar words, compiled from the es-ES.po source beside it. */
3
3
  declare const catalog: ListChromeCatalog;
4
4
  export default catalog;
@@ -1,5 +1,5 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /** The Spanish list chrome and list dates, compiled from the es-ES.po source beside it. */
2
+ /** The Spanish list chrome, list dates and sidebar words, compiled from the es-ES.po source beside it. */
3
3
  const catalog = {
4
4
  '': { lang: 'es-ES', 'plural-forms': 'nplurals=2; plural=(n != 1);' },
5
5
  '%1$d of %2$d Item': ['%1$d de %2$d elemento', '%1$d de %2$d elementos'],
@@ -81,11 +81,13 @@ const catalog = {
81
81
  'Automatically load more content as you scroll, instead of showing pagination links.': [
82
82
  'Carga automáticamente más contenido a medida que navegas, en lugar de mostrar enlaces de paginación.',
83
83
  ],
84
+ Back: ['Volver'],
84
85
  Before: ['Antes'],
85
86
  'Before (inc)': ['Antes (incl.)'],
86
87
  'Between (inc)': ['Entre (incl.)'],
87
88
  Cancel: ['Cancelar'],
88
89
  Close: ['Cerrar'],
90
+ 'Close navigation panel': ['Cerrar el panel de navegación'],
89
91
  Conditions: ['Condiciones'],
90
92
  Contains: ['Contiene'],
91
93
  'Coordinated Universal Time': ['Hora universal coordinada'],
@@ -144,6 +146,7 @@ const catalog = {
144
146
  'Move left': ['Mover a la izquierda'],
145
147
  'Move right': ['Mover a la derecha'],
146
148
  'Navigate to item': ['Navegar hasta el elemento'],
149
+ Navigation: ['Navegación'],
147
150
  'Navigation bar': ['Barra de navegación'],
148
151
  'Next month': ['Mes siguiente'],
149
152
  'Next page': ['Página siguiente'],
@@ -156,6 +159,7 @@ const catalog = {
156
159
  October: ['octubre'],
157
160
  'October abbreviation\u0004Oct': ['Oct'],
158
161
  On: ['El'],
162
+ 'Open navigation panel': ['Abrir el panel de navegación'],
159
163
  Optional: ['Opcional'],
160
164
  Order: ['Orden'],
161
165
  'Original aspect ratio': ['Proporción original'],
@@ -1,4 +1,4 @@
1
1
  import type { ListChromeCatalog } from '../list-chrome.js';
2
- /** The French list dates, compiled from the fr-FR.po source beside it. */
2
+ /** The French list dates, dialog words and sidebar words, compiled from the fr-FR.po source beside it. */
3
3
  declare const catalog: ListChromeCatalog;
4
4
  export default catalog;
@@ -1,5 +1,5 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /** The French list dates, compiled from the fr-FR.po source beside it. */
2
+ /** The French list dates, dialog words and sidebar words, compiled from the fr-FR.po source beside it. */
3
3
  const catalog = {
4
4
  '': { lang: 'fr-FR', 'plural-forms': 'nplurals=2; plural=(n > 1);' },
5
5
  AM: ['AM'],
@@ -7,6 +7,8 @@ const catalog = {
7
7
  'April abbreviation\u0004Apr': ['Avr'],
8
8
  August: ['août'],
9
9
  'August abbreviation\u0004Aug': ['Août'],
10
+ Back: ['Retour'],
11
+ 'Close navigation panel': ['Fermer le panneau de navigation'],
10
12
  December: ['décembre'],
11
13
  'December abbreviation\u0004Dec': ['Déc'],
12
14
  'F j, Y g:i a': ['d F Y G\\hi'],
@@ -28,10 +30,12 @@ const catalog = {
28
30
  'May abbreviation\u0004May': ['Mai'],
29
31
  Mon: ['Lun'],
30
32
  Monday: ['lundi'],
33
+ Navigation: ['Navigation'],
31
34
  November: ['novembre'],
32
35
  'November abbreviation\u0004Nov': ['Nov'],
33
36
  October: ['octobre'],
34
37
  'October abbreviation\u0004Oct': ['Oct'],
38
+ 'Open navigation panel': ['Ouvrir le panneau de navigation'],
35
39
  PM: ['PM'],
36
40
  Sat: ['Sam'],
37
41
  Saturday: ['samedi'],
@@ -1,6 +1,6 @@
1
1
  /** A compiled catalogue as the i18n runtime reads it, the metadata entry first. */
2
2
  export type ListChromeCatalog = Record<string, string[] | Record<string, string>>;
3
- /** The text domain the WordPress list chrome and list dates read their strings from. */
3
+ /** The text domain the WordPress list chrome, the list dates and godmin's sidebar words read their strings from. */
4
4
  export declare const LIST_CHROME_DOMAIN = "default";
5
5
  /**
6
6
  * Returns the list chrome catalogue this package ships for a language.
@@ -1,5 +1,5 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /** The text domain the WordPress list chrome and list dates read their strings from. */
2
+ /** The text domain the WordPress list chrome, the list dates and godmin's sidebar words read their strings from. */
3
3
  export const LIST_CHROME_DOMAIN = 'default';
4
4
  /** The list chrome and list dates catalogue this package ships for each language it has one for. */
5
5
  const SHIPPED = {
@@ -9,7 +9,7 @@ export interface ListEmptyProps {
9
9
  hint?: string;
10
10
  }
11
11
  /**
12
- * Renders what a list shows when it has no rows: an icon, a title and an optional hint.
12
+ * Renders what a list shows when it has no rows: an icon, a title one level under the page title and an optional hint.
13
13
  * @param props - The icon, the title and the hint.
14
14
  * @returns The empty state element.
15
15
  */
@@ -1,11 +1,13 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
  import { EmptyState } from '@wordpress/ui';
4
+ import { useHeadingUnderPage } from './page.js';
4
5
  /**
5
- * Renders what a list shows when it has no rows: an icon, a title and an optional hint.
6
+ * Renders what a list shows when it has no rows: an icon, a title one level under the page title and an optional hint.
6
7
  * @param props - The icon, the title and the hint.
7
8
  * @returns The empty state element.
8
9
  */
9
10
  export function ListEmpty({ icon, title, hint }) {
10
- return (_jsxs(EmptyState.Root, { className: "godmin-empty", children: [_jsx(EmptyState.Icon, { icon: icon }), _jsx(EmptyState.Title, { children: title }), hint === undefined ? null : _jsx(EmptyState.Description, { children: hint })] }));
11
+ const Heading = useHeadingUnderPage();
12
+ return (_jsxs(EmptyState.Root, { className: "godmin-empty", children: [_jsx(EmptyState.Icon, { icon: icon }), _jsx(EmptyState.Title, { render: _jsx(Heading, {}), children: title }), hint === undefined ? null : _jsx(EmptyState.Description, { children: hint })] }));
11
13
  }
@@ -0,0 +1,12 @@
1
+ export interface MenuCountProps {
2
+ /** The number the count shows, nothing drawn at zero or below. */
3
+ count: number;
4
+ /** The sentence a screen reader reads in place of the number, such as "1 update available". */
5
+ label: string;
6
+ }
7
+ /**
8
+ * Renders the small count beside a menu label, such as the number of pending updates.
9
+ * @param props - The number and the sentence a screen reader reads for it.
10
+ * @returns The count element, or null when there is nothing to count.
11
+ */
12
+ export declare function MenuCount({ count, label }: MenuCountProps): import("react").JSX.Element | null;
@@ -0,0 +1,14 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { Badge, VisuallyHidden } from '@wordpress/ui';
4
+ /**
5
+ * Renders the small count beside a menu label, such as the number of pending updates.
6
+ * @param props - The number and the sentence a screen reader reads for it.
7
+ * @returns The count element, or null when there is nothing to count.
8
+ */
9
+ export function MenuCount({ count, label }) {
10
+ if (!(count > 0)) {
11
+ return null;
12
+ }
13
+ return (_jsxs("span", { className: "godmin-menu-count", children: [_jsx(Badge, { intent: "high", className: "godmin-menu-count__badge", "aria-hidden": "true", children: count.toLocaleString() }), _jsx(VisuallyHidden, { render: _jsx("span", {}), children: label })] }));
14
+ }
@@ -0,0 +1,29 @@
1
+ import type { ReactElement } from 'react';
2
+ import type { Can } from './navigation-state.js';
3
+ /** One row of a sidebar menu, as data. WordPress's new admin names it MenuItem too. */
4
+ export interface MenuItem {
5
+ /** The words the row shows. */
6
+ label: string;
7
+ /** A real address with its params filled in, such as '/users/42'. */
8
+ to: string;
9
+ /** A glyph from `@wordpress/icons`, drawn at 24px. */
10
+ icon?: ReactElement;
11
+ /** The capability the reader must hold, besides the ones the routes it opens ask for. */
12
+ capability?: string;
13
+ /** The row shown in this one's place when the reader cannot open it. */
14
+ fallback?: MenuItem;
15
+ }
16
+ /**
17
+ * Tells whether a reader may open every route an address opens, parents and params included.
18
+ * @param capabilities - The capability of every route the address opens.
19
+ * @param can - The check of a capability, absent outside a Navigation.
20
+ * @returns Whether the check allows every one of them, so with no check only routes that name none.
21
+ */
22
+ export declare function canOpenRoutes(capabilities: readonly string[], can: Can | undefined): boolean;
23
+ /**
24
+ * Returns the check of whether the reader may access a row: its own capability and that of every route it opens.
25
+ * A row that names a capability fails when can is absent.
26
+ * @param can - Tells whether the reader holds a capability.
27
+ * @returns The check of one row.
28
+ */
29
+ export declare function useCanAccess(can?: (capability: string) => boolean): (item: Pick<MenuItem, 'to' | 'capability'>) => boolean;
@@ -0,0 +1,33 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { useRouter } from '@tanstack/react-router';
3
+ import { useCallback } from 'react';
4
+ import { findRouteCapabilities } from './path-matching.js';
5
+ /**
6
+ * Tells whether a reader holds a capability, never when there is no check.
7
+ * @param can - The check of a capability, absent outside a Navigation.
8
+ * @param capability - The capability asked for.
9
+ * @returns Whether the check allows it.
10
+ */
11
+ function holds(can, capability) {
12
+ return can?.(capability) === true;
13
+ }
14
+ /**
15
+ * Tells whether a reader may open every route an address opens, parents and params included.
16
+ * @param capabilities - The capability of every route the address opens.
17
+ * @param can - The check of a capability, absent outside a Navigation.
18
+ * @returns Whether the check allows every one of them, so with no check only routes that name none.
19
+ */
20
+ export function canOpenRoutes(capabilities, can) {
21
+ return capabilities.every((capability) => holds(can, capability));
22
+ }
23
+ /**
24
+ * Returns the check of whether the reader may access a row: its own capability and that of every route it opens.
25
+ * A row that names a capability fails when can is absent.
26
+ * @param can - Tells whether the reader holds a capability.
27
+ * @returns The check of one row.
28
+ */
29
+ export function useCanAccess(can) {
30
+ const router = useRouter();
31
+ return useCallback((item) => (item.capability === undefined || holds(can, item.capability)) &&
32
+ canOpenRoutes(findRouteCapabilities(router, { to: item.to }), can), [router, can]);
33
+ }
@@ -0,0 +1,45 @@
1
+ import type { AnyRouter, LinkComponentProps, RegisteredRouter } from '@tanstack/react-router';
2
+ import type { ReactElement, ReactNode } from 'react';
3
+ import type { RowRoutes } from './path-matching.js';
4
+ /** The class every sidebar row link carries. */
5
+ export declare const ROW_CLASS = "godmin-navigation-item";
6
+ /**
7
+ * A row that goes to a page. Takes the TanStack Link props, such as to, params, search, className and onClick.
8
+ * An address with a scheme draws a plain link. Sits inside a NavigationList.
9
+ */
10
+ export type NavigationItemProps<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> & {
11
+ /** A glyph from `@wordpress/icons`, drawn at 24px. */
12
+ icon?: ReactElement;
13
+ /** Drawn at the end of the row, such as a MenuCount. */
14
+ suffix?: ReactNode;
15
+ children: ReactNode;
16
+ };
17
+ /** What a sidebar row draws. */
18
+ interface RowProps {
19
+ /** The TanStack Link props of the row. */
20
+ link: LinkComponentProps;
21
+ /** Where the row goes and what the routes it opens declare. */
22
+ routes: RowRoutes;
23
+ /** A glyph from `@wordpress/icons`, drawn at 24px. */
24
+ icon: ReactElement | undefined;
25
+ /** The classes of the row link, before the class the app gives. */
26
+ className: string;
27
+ /** The id of the row link, in place of the one the app gives, when the row needs one. */
28
+ id?: string;
29
+ /** What ends the row, such as a suffix or a chevron. */
30
+ end?: ReactNode;
31
+ children: ReactNode;
32
+ }
33
+ /**
34
+ * Renders a sidebar row as a list item holding its link, or nothing when the reader may not open its routes.
35
+ * @param props - The link props, where the row goes, the icon, the classes, the id, the end of the row and its label.
36
+ * @returns The list item element, or null.
37
+ */
38
+ export declare function Row({ link, routes, icon, className, id, end, children }: RowProps): import("react").JSX.Element | null;
39
+ /**
40
+ * Renders a sidebar row that goes to a page: its icon, its label and its suffix, current on every address under it.
41
+ * @param props - The TanStack Link props, the icon, the suffix and the label.
42
+ * @returns The row element, or null when its address opens a route the reader may not open.
43
+ */
44
+ export declare function NavigationItem<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 }: NavigationItemProps<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): import("react").JSX.Element;
45
+ export {};
@@ -0,0 +1,50 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { Link, useRouter } from '@tanstack/react-router';
4
+ import { Icon } from '@wordpress/icons';
5
+ import { useContext } from 'react';
6
+ import { canOpenRoutes } from './menu-item.js';
7
+ import { IconPlaceholderContext, ScreenContext } from './navigation-state.js';
8
+ import { findRowRoutes } from './path-matching.js';
9
+ /** The class every sidebar row link carries. */
10
+ export const ROW_CLASS = 'godmin-navigation-item';
11
+ /** The class of a row icon and of the placeholder drawn in its place. */
12
+ const ICON_CLASS = 'godmin-navigation-item__icon';
13
+ /**
14
+ * Renders the icon of a row, the placeholder in its place when the rows beside it have icons, or nothing.
15
+ * @param props - The glyph of the row, if any.
16
+ * @returns The icon element, the placeholder, or null.
17
+ */
18
+ function RowIcon({ icon }) {
19
+ const placeholder = useContext(IconPlaceholderContext);
20
+ if (icon !== undefined) {
21
+ return _jsx(Icon, { icon: icon, size: 24, className: ICON_CLASS });
22
+ }
23
+ return placeholder ? _jsx("span", { className: ICON_CLASS, "aria-hidden": "true" }) : null;
24
+ }
25
+ /**
26
+ * Renders a sidebar row as a list item holding its link, or nothing when the reader may not open its routes.
27
+ * @param props - The link props, where the row goes, the icon, the classes, the id, the end of the row and its label.
28
+ * @returns The list item element, or null.
29
+ */
30
+ export function Row({ link, routes, icon, className, id, end, children }) {
31
+ const { can } = useContext(ScreenContext);
32
+ if (!canOpenRoutes(routes.capabilities, can)) {
33
+ return null;
34
+ }
35
+ return (_jsx("li", { children: _jsxs(Link, { ...link, id: id ?? link.id, className: link.className === undefined ? className : `${className} ${link.className}`, children: [_jsx(RowIcon, { icon: icon }), _jsx("div", { className: "godmin-navigation-item__label", children: children }), end] }) }));
36
+ }
37
+ /**
38
+ * Renders a sidebar row that goes to a page: its icon, its label and its suffix, current on every address under it.
39
+ * @param props - The TanStack Link props, the icon, the suffix and the label.
40
+ * @returns The row element, or null when its address opens a route the reader may not open.
41
+ */
42
+ export function NavigationItem({ icon, suffix, children, ...link }) {
43
+ const router = useRouter();
44
+ const address = link;
45
+ const routes = findRowRoutes(router, address);
46
+ if (suffix === undefined) {
47
+ return (_jsx(Row, { link: address, routes: routes, icon: icon, className: ROW_CLASS, children: children }));
48
+ }
49
+ return (_jsx(Row, { link: address, routes: routes, icon: icon, className: `${ROW_CLASS} ${ROW_CLASS}--with-suffix`, end: _jsx("span", { className: "godmin-navigation-item__suffix", children: suffix }), children: children }));
50
+ }
@@ -0,0 +1,14 @@
1
+ import type { ReactNode } from 'react';
2
+ import type { MenuItem } from './menu-item.js';
3
+ export interface NavigationListProps {
4
+ /** The rows as data, checked against the can of the Navigation the list sits in. */
5
+ items?: readonly MenuItem[];
6
+ /** Rows the app draws itself, each a NavigationItem or a DrilldownItem, after the rows of items. */
7
+ children?: ReactNode;
8
+ }
9
+ /**
10
+ * Renders the rows of a sidebar screen as a list: the rows of items the reader may access, then the rows the app draws.
11
+ * @param props - The rows as data and the rows the app draws itself.
12
+ * @returns The list element.
13
+ */
14
+ export declare function NavigationList({ items, children }: NavigationListProps): import("react").JSX.Element;
@@ -0,0 +1,62 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { useRouter, useRouterState } from '@tanstack/react-router';
4
+ import { Children, isValidElement, useContext } from 'react';
5
+ import { DrilldownItem } from './drilldown-item.js';
6
+ import { canOpenRoutes, useCanAccess } from './menu-item.js';
7
+ import { NavigationItem } from './navigation-item.js';
8
+ import { IconPlaceholderContext, ScreenContext } from './navigation-state.js';
9
+ import { findDrilldownParent, findRouteCapabilities, findSidebarMatch } from './path-matching.js';
10
+ /**
11
+ * Returns the row a reader sees in a menu item's place: the item, else its fallback, else nothing.
12
+ * @param item - The menu item, or the fallback of one.
13
+ * @param canAccess - Tells whether the reader may access a row.
14
+ * @returns The first of the item and its fallbacks the reader may access, or undefined.
15
+ */
16
+ function shownRow(item, canAccess) {
17
+ if (item === undefined || canAccess(item)) {
18
+ return item;
19
+ }
20
+ return shownRow(item.fallback, canAccess);
21
+ }
22
+ /**
23
+ * Tells whether a row the app draws shows with an icon.
24
+ * @param child - The row element.
25
+ * @param router - The router its address resolves on.
26
+ * @param can - Tells whether the reader holds a capability.
27
+ * @returns Whether the row has an icon and the reader may open every route its address opens.
28
+ */
29
+ function showsIcon(child, router, can) {
30
+ if (!isValidElement(child) || child.props.icon === undefined) {
31
+ return false;
32
+ }
33
+ return canOpenRoutes(findRouteCapabilities(router, child.props), can);
34
+ }
35
+ /**
36
+ * Renders a row of data as a DrilldownItem when it opens a sub menu other than the one shown, else a NavigationItem.
37
+ * @param props - The row, and the id of the sub menu route shown now, undefined on the root screen.
38
+ * @returns The row element.
39
+ */
40
+ function DataRow({ item, shown }) {
41
+ const router = useRouter();
42
+ const target = findDrilldownParent(router, { to: item.to });
43
+ if (target !== undefined && target !== shown) {
44
+ return (_jsx(DrilldownItem, { to: item.to, icon: item.icon, children: item.label }));
45
+ }
46
+ return (_jsx(NavigationItem, { to: item.to, icon: item.icon, children: item.label }));
47
+ }
48
+ /**
49
+ * Renders the rows of a sidebar screen as a list: the rows of items the reader may access, then the rows the app draws.
50
+ * @param props - The rows as data and the rows the app draws itself.
51
+ * @returns The list element.
52
+ */
53
+ export function NavigationList({ items = [], children }) {
54
+ const router = useRouter();
55
+ const { can } = useContext(ScreenContext);
56
+ const canAccess = useCanAccess(can);
57
+ const shown = useRouterState({ select: (state) => findSidebarMatch(state.matches)?.routeId });
58
+ const rows = items.map((item) => shownRow(item, canAccess));
59
+ const placeholder = rows.some((row) => row?.icon !== undefined) ||
60
+ Children.toArray(children).some((child) => showsIcon(child, router, can));
61
+ return (_jsx(IconPlaceholderContext.Provider, { value: placeholder, children: _jsxs("ul", { role: "list", className: "godmin-navigation-list", children: [rows.map((row) => (row === undefined ? null : _jsx(DataRow, { item: row, shown: shown }, row.to))), children] }) }));
62
+ }
@@ -0,0 +1,24 @@
1
+ import type { ReactElement, ReactNode } from 'react';
2
+ export interface NavigationScreenProps {
3
+ /** The title, an h1. A node, so the root screen can hold the brand. */
4
+ title: ReactNode;
5
+ /**
6
+ * The app's router link Back renders through. Inside a Navigation a sub screen
7
+ * without one goes home, and the root draws no Back.
8
+ */
9
+ back?: ReactElement<Record<string, unknown>>;
10
+ /** The name of Back, godmin's translated "Back" when absent. */
11
+ backLabel?: string;
12
+ description?: ReactNode;
13
+ actions?: ReactNode;
14
+ /** The sticky footer of this one screen. */
15
+ footer?: ReactNode;
16
+ children: ReactNode;
17
+ }
18
+ /**
19
+ * Renders a sidebar screen as the Site Editor draws it: a title row with Back, the title and the actions,
20
+ * then the description and the content, then an optional footer.
21
+ * @param props - The title, Back's link and label, and the regions.
22
+ * @returns The navigation screen element.
23
+ */
24
+ export declare function NavigationScreen({ title, back, backLabel, description, actions, footer, children, }: NavigationScreenProps): import("react").JSX.Element;