@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 +27 -2
- package/dist/base.css +292 -29
- package/dist/breakpoints.d.ts +7 -3
- package/dist/breakpoints.js +8 -4
- package/dist/drilldown-item.d.ts +19 -0
- package/dist/drilldown-item.js +31 -0
- package/dist/frame.d.ts +16 -8
- package/dist/frame.js +44 -23
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +5 -1
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +5 -1
- package/dist/list-chrome.d.ts +1 -1
- package/dist/list-chrome.js +1 -1
- package/dist/list-empty.d.ts +1 -1
- package/dist/list-empty.js +4 -2
- package/dist/menu-item.d.ts +36 -0
- package/dist/menu-item.js +33 -0
- package/dist/navigation-item.d.ts +53 -0
- package/dist/navigation-item.js +58 -0
- package/dist/navigation-list.d.ts +14 -0
- package/dist/navigation-list.js +72 -0
- package/dist/navigation-screen.d.ts +24 -0
- package/dist/navigation-screen.js +47 -0
- package/dist/navigation-state.d.ts +83 -0
- package/dist/navigation-state.js +88 -0
- package/dist/navigation.d.ts +23 -0
- package/dist/navigation.js +133 -0
- package/dist/page-tabs.d.ts +5 -4
- package/dist/page-tabs.js +12 -3
- package/dist/page.d.ts +20 -6
- package/dist/page.js +32 -10
- package/dist/path-matching.d.ts +68 -0
- package/dist/path-matching.js +126 -0
- package/dist/router.d.ts +24 -2
- package/dist/router.js +16 -3
- package/package.json +3 -6
- package/dist/nav-screen.d.ts +0 -17
- package/dist/nav-screen.js +0 -31
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { MouseEvent, ReactElement } from 'react';
|
|
2
|
+
/** Tells whether the reader holds a capability. */
|
|
3
|
+
export type Can = (capability: string) => boolean;
|
|
4
|
+
/** Which way the sidebar moved: into a sub menu, or back out of one. */
|
|
5
|
+
export type Direction = 'forward' | 'backward';
|
|
6
|
+
/** A move a drilldown row or Back makes, read once by the screen it lands on. */
|
|
7
|
+
export interface Move {
|
|
8
|
+
/** Which way the move goes. */
|
|
9
|
+
direction: Direction;
|
|
10
|
+
/** The pathname and search the move goes to. */
|
|
11
|
+
address: string;
|
|
12
|
+
/** The drilldown row a forward move leaves, or the row a backward move returns to. */
|
|
13
|
+
rowId?: string;
|
|
14
|
+
}
|
|
15
|
+
/** What the sidebar parts record about a move, read once by the menu and the drawer. */
|
|
16
|
+
export interface NavigationState {
|
|
17
|
+
/** The move a drilldown row or Back made, until a screen lands from it. */
|
|
18
|
+
move?: Move;
|
|
19
|
+
/** The id of the drilldown row that opened the sub menu shown, for Back to focus. */
|
|
20
|
+
openedFrom?: string;
|
|
21
|
+
/** The address the phone drawer stays open on, until the next page change. */
|
|
22
|
+
drawerStaysOn?: string;
|
|
23
|
+
}
|
|
24
|
+
/** The state the sidebar parts share, which a Frame.Root creates and provides. */
|
|
25
|
+
export declare const NavigationStateContext: import("react").Context<NavigationState | undefined>;
|
|
26
|
+
/** What a Navigation hands each screen it draws. */
|
|
27
|
+
export interface ScreenState {
|
|
28
|
+
/** Whether the screen is the root screen, drawn from the menu items. */
|
|
29
|
+
isRoot?: boolean;
|
|
30
|
+
/** The app's link to the list its home address lands on, where Back on a sub menu goes. */
|
|
31
|
+
home?: ReactElement<Record<string, unknown>>;
|
|
32
|
+
/** The app's check of a capability, read by every row inside. */
|
|
33
|
+
can?: Can;
|
|
34
|
+
/** Returns the pathname and search an app's router link goes to, undefined when it is the one already open. */
|
|
35
|
+
targetOf?: (link: ReactElement<Record<string, unknown>>) => string | undefined;
|
|
36
|
+
}
|
|
37
|
+
/** The screen a sidebar part sits in, empty outside a Navigation. */
|
|
38
|
+
export declare const ScreenContext: import("react").Context<ScreenState>;
|
|
39
|
+
/** Whether a row with no icon draws a 24px placeholder in its place. */
|
|
40
|
+
export declare const IconPlaceholderContext: import("react").Context<boolean>;
|
|
41
|
+
/**
|
|
42
|
+
* Creates the state of a frame with no move recorded.
|
|
43
|
+
* @returns The state.
|
|
44
|
+
*/
|
|
45
|
+
export declare function createNavigationState(): NavigationState;
|
|
46
|
+
/**
|
|
47
|
+
* Tells whether a click follows its link in the same tab, as the router follows it.
|
|
48
|
+
* @param event - The click.
|
|
49
|
+
* @returns Whether it is a main button click with no modifier key, not stopped, on a link that opens in this tab.
|
|
50
|
+
*/
|
|
51
|
+
export declare function isPlainClick(event: MouseEvent): boolean;
|
|
52
|
+
/**
|
|
53
|
+
* Records a move into a sub menu from a drilldown row, unless the row goes nowhere.
|
|
54
|
+
* @param state - The state of the frame.
|
|
55
|
+
* @param rowId - The id of the row.
|
|
56
|
+
* @param address - The pathname and search the row goes to, undefined when it is the one already open.
|
|
57
|
+
*/
|
|
58
|
+
export declare function recordDrilldown(state: NavigationState, rowId: string, address: string | undefined): void;
|
|
59
|
+
/**
|
|
60
|
+
* Records a move back out of a sub menu, unless Back goes nowhere.
|
|
61
|
+
* @param state - The state of the frame.
|
|
62
|
+
* @param address - The pathname and search Back goes to, undefined when it is the one already open.
|
|
63
|
+
*/
|
|
64
|
+
export declare function recordBack(state: NavigationState, address: string | undefined): void;
|
|
65
|
+
/**
|
|
66
|
+
* Reads once the move a new screen lands from, when the screen's address is the one the move went to.
|
|
67
|
+
* @param state - The state of the frame.
|
|
68
|
+
* @param address - The pathname and search the screen landed on.
|
|
69
|
+
* @returns The move, a backward one with the row it returns to, or undefined when the screen came from anywhere else.
|
|
70
|
+
*/
|
|
71
|
+
export declare function takeMove(state: NavigationState, address: string): Move | undefined;
|
|
72
|
+
/**
|
|
73
|
+
* Forgets a move that kept the screen.
|
|
74
|
+
* @param state - The state of the frame.
|
|
75
|
+
*/
|
|
76
|
+
export declare function forgetUnusedMove(state: NavigationState): void;
|
|
77
|
+
/**
|
|
78
|
+
* Reads once whether the phone drawer stays open on the page just opened.
|
|
79
|
+
* @param state - The state of the frame.
|
|
80
|
+
* @param location - The location the frame shows now.
|
|
81
|
+
* @returns Whether a drilldown row or Back went to that location.
|
|
82
|
+
*/
|
|
83
|
+
export declare function takeDrawerStays(state: NavigationState, location: string | undefined): boolean;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { createContext } from 'react';
|
|
3
|
+
/** The state the sidebar parts share, which a Frame.Root creates and provides. */
|
|
4
|
+
export const NavigationStateContext = createContext(undefined);
|
|
5
|
+
/** The screen a sidebar part sits in, empty outside a Navigation. */
|
|
6
|
+
export const ScreenContext = createContext({});
|
|
7
|
+
/** Whether a row with no icon draws a 24px placeholder in its place. */
|
|
8
|
+
export const IconPlaceholderContext = createContext(false);
|
|
9
|
+
/**
|
|
10
|
+
* Creates the state of a frame with no move recorded.
|
|
11
|
+
* @returns The state.
|
|
12
|
+
*/
|
|
13
|
+
export function createNavigationState() {
|
|
14
|
+
return {};
|
|
15
|
+
}
|
|
16
|
+
/** The link targets that open in the same tab, as TanStack's Link reads them. */
|
|
17
|
+
const SAME_TAB = ['', '_self'];
|
|
18
|
+
/**
|
|
19
|
+
* Tells whether a click follows its link in the same tab, as the router follows it.
|
|
20
|
+
* @param event - The click.
|
|
21
|
+
* @returns Whether it is a main button click with no modifier key, not stopped, on a link that opens in this tab.
|
|
22
|
+
*/
|
|
23
|
+
export function isPlainClick(event) {
|
|
24
|
+
return (event.button === 0 &&
|
|
25
|
+
!event.defaultPrevented &&
|
|
26
|
+
!(event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) &&
|
|
27
|
+
SAME_TAB.includes(event.currentTarget.getAttribute('target') ?? ''));
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Records a move into a sub menu from a drilldown row, unless the row goes nowhere.
|
|
31
|
+
* @param state - The state of the frame.
|
|
32
|
+
* @param rowId - The id of the row.
|
|
33
|
+
* @param address - The pathname and search the row goes to, undefined when it is the one already open.
|
|
34
|
+
*/
|
|
35
|
+
export function recordDrilldown(state, rowId, address) {
|
|
36
|
+
if (address !== undefined) {
|
|
37
|
+
state.move = { direction: 'forward', address, rowId };
|
|
38
|
+
state.drawerStaysOn = address;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Records a move back out of a sub menu, unless Back goes nowhere.
|
|
43
|
+
* @param state - The state of the frame.
|
|
44
|
+
* @param address - The pathname and search Back goes to, undefined when it is the one already open.
|
|
45
|
+
*/
|
|
46
|
+
export function recordBack(state, address) {
|
|
47
|
+
if (address !== undefined) {
|
|
48
|
+
state.move = { direction: 'backward', address };
|
|
49
|
+
state.drawerStaysOn = address;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Reads once the move a new screen lands from, when the screen's address is the one the move went to.
|
|
54
|
+
* @param state - The state of the frame.
|
|
55
|
+
* @param address - The pathname and search the screen landed on.
|
|
56
|
+
* @returns The move, a backward one with the row it returns to, or undefined when the screen came from anywhere else.
|
|
57
|
+
*/
|
|
58
|
+
export function takeMove(state, address) {
|
|
59
|
+
const { move, openedFrom } = state;
|
|
60
|
+
state.move = undefined;
|
|
61
|
+
state.openedFrom = undefined;
|
|
62
|
+
if (move?.address !== address) {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
if (move.direction === 'forward') {
|
|
66
|
+
state.openedFrom = move.rowId;
|
|
67
|
+
return move;
|
|
68
|
+
}
|
|
69
|
+
return { ...move, rowId: openedFrom };
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Forgets a move that kept the screen.
|
|
73
|
+
* @param state - The state of the frame.
|
|
74
|
+
*/
|
|
75
|
+
export function forgetUnusedMove(state) {
|
|
76
|
+
state.move = undefined;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Reads once whether the phone drawer stays open on the page just opened.
|
|
80
|
+
* @param state - The state of the frame.
|
|
81
|
+
* @param location - The location the frame shows now.
|
|
82
|
+
* @returns Whether a drilldown row or Back went to that location.
|
|
83
|
+
*/
|
|
84
|
+
export function takeDrawerStays(state, location) {
|
|
85
|
+
const stays = location !== undefined && state.drawerStaysOn === location;
|
|
86
|
+
state.drawerStaysOn = undefined;
|
|
87
|
+
return stays;
|
|
88
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { ReactElement, ReactNode } from 'react';
|
|
2
|
+
import type { MenuItem } from './menu-item.js';
|
|
3
|
+
import type { Can } from './navigation-state.js';
|
|
4
|
+
export interface NavigationProps {
|
|
5
|
+
/** The title of the root screen, the brand. */
|
|
6
|
+
title: ReactNode;
|
|
7
|
+
/** The rows of the root screen. */
|
|
8
|
+
items: readonly MenuItem[];
|
|
9
|
+
/** The app's link to the list its home address lands on. Back on a sub menu goes there. */
|
|
10
|
+
home: ReactElement<Record<string, unknown>>;
|
|
11
|
+
/**
|
|
12
|
+
* Tells whether the reader holds a capability, for every row inside.
|
|
13
|
+
* When absent, a row that names a capability is hidden.
|
|
14
|
+
*/
|
|
15
|
+
can?: Can;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Renders the sidebar menu, as WordPress's new admin names it: the root screen drawn from its title and rows,
|
|
19
|
+
* or the Sidebar screen of the deepest matched route, keyed by that route alone and sliding in on a move.
|
|
20
|
+
* @param props - The root title and rows, the app's home and its check of a capability.
|
|
21
|
+
* @returns The sidebar menu element.
|
|
22
|
+
*/
|
|
23
|
+
export declare function Navigation({ title, items, home, can }: NavigationProps): import("react").JSX.Element;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
import { useRouter, useRouterState } from '@tanstack/react-router';
|
|
4
|
+
import { Suspense, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
|
|
5
|
+
import { NavigationList } from './navigation-list.js';
|
|
6
|
+
import { NavigationScreen } from './navigation-screen.js';
|
|
7
|
+
import { NavigationStateContext, ScreenContext, forgetUnusedMove, takeMove } from './navigation-state.js';
|
|
8
|
+
import { findMoveTarget, findSidebarMatch, locationAddress } from './path-matching.js';
|
|
9
|
+
/** The key of the root screen, shown when no matched route declares a Sidebar. */
|
|
10
|
+
const ROOT_KEY = 'root';
|
|
11
|
+
/** The class of the keyed wrapper a screen slides in, the Site Editor's name for it. */
|
|
12
|
+
const WRAPPER = 'godmin-navigation__screen-wrapper';
|
|
13
|
+
/** The error Navigation throws with no Frame.Root above it. */
|
|
14
|
+
const NO_FRAME = 'Navigation must sit inside a Frame.Root, which holds the moves its screens share.';
|
|
15
|
+
/** The controls the Tab key reaches, the ones a screen may focus after a move. */
|
|
16
|
+
const TABBABLE = [
|
|
17
|
+
'a[href]',
|
|
18
|
+
'button:not(:disabled)',
|
|
19
|
+
'input:not(:disabled):not([type="hidden"])',
|
|
20
|
+
'select:not(:disabled)',
|
|
21
|
+
'textarea:not(:disabled)',
|
|
22
|
+
'[tabindex]',
|
|
23
|
+
]
|
|
24
|
+
.map((control) => `${control}:not([tabindex="-1"])`)
|
|
25
|
+
.join(', ');
|
|
26
|
+
/**
|
|
27
|
+
* Returns the sidebar screen the current address shows, keyed by its route alone.
|
|
28
|
+
* @returns The screen's key and its Sidebar.
|
|
29
|
+
*/
|
|
30
|
+
function useSidebarParent() {
|
|
31
|
+
const key = useRouterState({ select: (state) => findSidebarMatch(state.matches)?.routeId ?? ROOT_KEY });
|
|
32
|
+
const Sidebar = useRouterState({ select: (state) => findSidebarMatch(state.matches)?.staticData.Sidebar });
|
|
33
|
+
return { key, Sidebar };
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Returns the address of the deepest matched route.
|
|
37
|
+
* @returns Its pathname and search.
|
|
38
|
+
*/
|
|
39
|
+
function useMatchedAddress() {
|
|
40
|
+
return useRouterState({
|
|
41
|
+
select: (state) => state.matches
|
|
42
|
+
.slice(-1)
|
|
43
|
+
.map((deepest) => deepest.pathname + JSON.stringify(deepest.search))
|
|
44
|
+
.join(),
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Returns the moves the Frame.Root above records.
|
|
49
|
+
* @returns The state of the frame.
|
|
50
|
+
*/
|
|
51
|
+
function useFrameState() {
|
|
52
|
+
const state = useContext(NavigationStateContext);
|
|
53
|
+
if (state === undefined) {
|
|
54
|
+
throw new Error(NO_FRAME);
|
|
55
|
+
}
|
|
56
|
+
return state;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Forgets a move whose routes matched without a change of screen.
|
|
60
|
+
* @param state - The state of the frame.
|
|
61
|
+
* @param key - The key of the screen shown.
|
|
62
|
+
*/
|
|
63
|
+
function useForgetUnusedMove(state, key) {
|
|
64
|
+
const address = useMatchedAddress();
|
|
65
|
+
const shown = useRef(key);
|
|
66
|
+
useEffect(() => {
|
|
67
|
+
if (shown.current === key) {
|
|
68
|
+
forgetUnusedMove(state);
|
|
69
|
+
}
|
|
70
|
+
shown.current = key;
|
|
71
|
+
}, [state, key, address]);
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Finds the drilldown row a backward move returns to.
|
|
75
|
+
* @param move - The move the screen landed from.
|
|
76
|
+
* @returns The row link, or null on a forward move or when the row is gone.
|
|
77
|
+
*/
|
|
78
|
+
function rowCameFrom(move) {
|
|
79
|
+
if (move.direction !== 'backward' || move.rowId === undefined) {
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
return document.getElementById(move.rowId);
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Finds what a screen focuses after a move: the row the reader came from on the way back,
|
|
86
|
+
* else its Back, else the first control the Tab key reaches, else the screen wrapper itself.
|
|
87
|
+
* @param wrapper - The keyed wrapper of the screen.
|
|
88
|
+
* @param move - The move the screen landed from.
|
|
89
|
+
* @returns The element to focus.
|
|
90
|
+
*/
|
|
91
|
+
function focusAfterMove(wrapper, move) {
|
|
92
|
+
return (rowCameFrom(move) ??
|
|
93
|
+
wrapper.querySelector('.godmin-navigation-screen__back') ??
|
|
94
|
+
wrapper.querySelector(TABBABLE) ??
|
|
95
|
+
wrapper);
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Renders the keyed wrapper of one screen, which slides in and takes focus after a move from a drilldown row or Back.
|
|
99
|
+
* @param props - The state of the frame and the screen.
|
|
100
|
+
* @returns The wrapper element.
|
|
101
|
+
*/
|
|
102
|
+
function ScreenWrapper({ state, children }) {
|
|
103
|
+
const router = useRouter();
|
|
104
|
+
const wrapper = useRef(null);
|
|
105
|
+
const [direction, setDirection] = useState();
|
|
106
|
+
useLayoutEffect(() => {
|
|
107
|
+
const move = takeMove(state, locationAddress(router.latestLocation));
|
|
108
|
+
if (move !== undefined) {
|
|
109
|
+
focusAfterMove(wrapper.current, move).focus();
|
|
110
|
+
setDirection(move.direction);
|
|
111
|
+
}
|
|
112
|
+
}, [state, router]);
|
|
113
|
+
return (_jsx("div", { ref: wrapper, tabIndex: -1, className: direction === undefined ? WRAPPER : `${WRAPPER} ${WRAPPER}--${direction}`, children: children }));
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Renders the sidebar menu, as WordPress's new admin names it: the root screen drawn from its title and rows,
|
|
117
|
+
* or the Sidebar screen of the deepest matched route, keyed by that route alone and sliding in on a move.
|
|
118
|
+
* @param props - The root title and rows, the app's home and its check of a capability.
|
|
119
|
+
* @returns The sidebar menu element.
|
|
120
|
+
*/
|
|
121
|
+
export function Navigation({ title, items, home, can }) {
|
|
122
|
+
const router = useRouter();
|
|
123
|
+
const state = useFrameState();
|
|
124
|
+
const { key, Sidebar } = useSidebarParent();
|
|
125
|
+
useForgetUnusedMove(state, key);
|
|
126
|
+
const screen = useMemo(() => ({
|
|
127
|
+
isRoot: Sidebar === undefined,
|
|
128
|
+
home,
|
|
129
|
+
can,
|
|
130
|
+
targetOf: (link) => findMoveTarget(router, link.props),
|
|
131
|
+
}), [Sidebar, home, can, router]);
|
|
132
|
+
return (_jsx("div", { className: "godmin-navigation", children: _jsx(ScreenContext.Provider, { value: screen, children: _jsx(Suspense, { fallback: null, children: _jsx(ScreenWrapper, { state: state, children: Sidebar === undefined ? (_jsx(NavigationScreen, { title: title, children: _jsx(NavigationList, { items: items }) })) : (_jsx(Sidebar, {})) }, key) }) }) }));
|
|
133
|
+
}
|
package/dist/page-tabs.d.ts
CHANGED
|
@@ -6,7 +6,8 @@ export interface PageTabsProps {
|
|
|
6
6
|
children: ReactNode;
|
|
7
7
|
}
|
|
8
8
|
/**
|
|
9
|
-
* Renders the tabs of a page as a navigation region
|
|
9
|
+
* Renders the tabs of a page as a navigation region holding a list of links, as admin-ui draws its page navigation.
|
|
10
|
+
* The list scrolls to the current tab and fades a cut edge.
|
|
10
11
|
* @param props - The navigation name and the tabs.
|
|
11
12
|
* @returns The tab navigation element.
|
|
12
13
|
*/
|
|
@@ -24,8 +25,8 @@ export interface PageTabProps {
|
|
|
24
25
|
children: ReactNode;
|
|
25
26
|
}
|
|
26
27
|
/**
|
|
27
|
-
* Renders one page tab as a
|
|
28
|
+
* Renders one page tab as a list item of the tab row holding its link.
|
|
28
29
|
* @param props - The address or the link element, whether it is current, and the label.
|
|
29
|
-
* @returns The tab
|
|
30
|
+
* @returns The tab list item element.
|
|
30
31
|
*/
|
|
31
|
-
export declare function PageTab(
|
|
32
|
+
export declare function PageTab(props: PageTabProps): import("react").JSX.Element;
|
package/dist/page-tabs.js
CHANGED
|
@@ -105,7 +105,8 @@ function useRevealCurrent(ref) {
|
|
|
105
105
|
});
|
|
106
106
|
}
|
|
107
107
|
/**
|
|
108
|
-
* Renders the tabs of a page as a navigation region
|
|
108
|
+
* Renders the tabs of a page as a navigation region holding a list of links, as admin-ui draws its page navigation.
|
|
109
|
+
* The list scrolls to the current tab and fades a cut edge.
|
|
109
110
|
* @param props - The navigation name and the tabs.
|
|
110
111
|
* @returns The tab navigation element.
|
|
111
112
|
*/
|
|
@@ -113,14 +114,14 @@ export function PageTabs({ label, children }) {
|
|
|
113
114
|
const ref = useRef(null);
|
|
114
115
|
useRevealCurrent(ref);
|
|
115
116
|
const className = useRowClass(ref);
|
|
116
|
-
return (_jsx("nav", { ref: ref, className: className, "
|
|
117
|
+
return (_jsx("nav", { "aria-label": label, children: _jsx("ul", { ref: ref, className: className, role: "list", children: children }) }));
|
|
117
118
|
}
|
|
118
119
|
/**
|
|
119
120
|
* Renders one page tab as a link, marked and underlined as the current page when it leads to the page on screen.
|
|
120
121
|
* @param props - The address or the link element, whether it is current, and the label.
|
|
121
122
|
* @returns The tab link element.
|
|
122
123
|
*/
|
|
123
|
-
|
|
124
|
+
function TabLink({ href, render, current = false, children }) {
|
|
124
125
|
const ariaCurrent = current ? 'page' : undefined;
|
|
125
126
|
const tabClass = current ? `${TAB_CLASS} ${CURRENT_CLASS}` : TAB_CLASS;
|
|
126
127
|
if (render === undefined) {
|
|
@@ -133,3 +134,11 @@ export function PageTab({ href, render, current = false, children }) {
|
|
|
133
134
|
children,
|
|
134
135
|
});
|
|
135
136
|
}
|
|
137
|
+
/**
|
|
138
|
+
* Renders one page tab as a list item of the tab row holding its link.
|
|
139
|
+
* @param props - The address or the link element, whether it is current, and the label.
|
|
140
|
+
* @returns The tab list item element.
|
|
141
|
+
*/
|
|
142
|
+
export function PageTab(props) {
|
|
143
|
+
return (_jsx("li", { children: _jsx(TabLink, { ...props }) }));
|
|
144
|
+
}
|
package/dist/page.d.ts
CHANGED
|
@@ -1,18 +1,29 @@
|
|
|
1
1
|
import { Text } from '@wordpress/ui';
|
|
2
2
|
import type { ComponentProps, ReactNode, Ref } from 'react';
|
|
3
3
|
type TextVariant = ComponentProps<typeof Text>['variant'];
|
|
4
|
+
/** The level of a page title, 1 as in WordPress's admin-ui Page, 2 on a screen beside the sidebar. */
|
|
5
|
+
type PageLevel = 1 | 2;
|
|
6
|
+
/** The heading element a level renders as. */
|
|
7
|
+
type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4';
|
|
8
|
+
/**
|
|
9
|
+
* Returns the heading element one level under the title of the Page around it, an h2 outside any Page.
|
|
10
|
+
* @returns The element name.
|
|
11
|
+
*/
|
|
12
|
+
export declare function useHeadingUnderPage(): HeadingTag;
|
|
4
13
|
/**
|
|
5
14
|
* Renders a screen's title as the page heading.
|
|
6
|
-
* @param props - The title text
|
|
15
|
+
* @param props - The title text, the type scale to render it at and its heading level, 1 when absent.
|
|
7
16
|
* @returns The page title element.
|
|
8
17
|
*/
|
|
9
|
-
export declare function PageTitle({ children, variant, }: {
|
|
18
|
+
export declare function PageTitle({ children, variant, level, }: {
|
|
10
19
|
children: ReactNode;
|
|
11
20
|
variant?: TextVariant;
|
|
21
|
+
level?: PageLevel;
|
|
12
22
|
}): import("react").JSX.Element;
|
|
13
23
|
/**
|
|
14
|
-
* Renders a section heading one size step above the field labels.
|
|
15
|
-
* @param props - The heading text, its level, and the id and tab index a screen moves
|
|
24
|
+
* Renders a section heading one size step above the field labels, one level deeper inside a level 2 Page.
|
|
25
|
+
* @param props - The heading text, its rank under a level 1 page title, and the id and tab index a screen moves
|
|
26
|
+
* focus with.
|
|
16
27
|
* @returns The section heading element.
|
|
17
28
|
*/
|
|
18
29
|
export declare function SectionTitle({ children, level, id, tabIndex, }: {
|
|
@@ -33,14 +44,17 @@ export interface PageProps {
|
|
|
33
44
|
/** The ref to the list region. */
|
|
34
45
|
listRef?: Ref<HTMLDivElement>;
|
|
35
46
|
className?: string;
|
|
47
|
+
/** The level of the page title, 1 as in WordPress's admin-ui Page. A screen beside the sidebar passes 2. */
|
|
48
|
+
headingLevel?: PageLevel;
|
|
36
49
|
children: ReactNode;
|
|
37
50
|
}
|
|
38
51
|
/**
|
|
39
52
|
* Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
|
|
40
|
-
* @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class
|
|
53
|
+
* @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
|
|
54
|
+
* and content.
|
|
41
55
|
* @returns The page element.
|
|
42
56
|
*/
|
|
43
|
-
export declare function Page({ title, subtitle, actions, tabs, aside, list, listLabel, listRef, className, children, }: PageProps): import("react").JSX.Element;
|
|
57
|
+
export declare function Page({ title, subtitle, actions, tabs, aside, list, listLabel, listRef, className, headingLevel, children, }: PageProps): import("react").JSX.Element;
|
|
44
58
|
/**
|
|
45
59
|
* Renders a failure message that a screen reader announces.
|
|
46
60
|
* @param props - The message to announce.
|
package/dist/page.js
CHANGED
|
@@ -2,22 +2,43 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
|
2
2
|
/* oxlint-disable react/only-export-components -- the page kit ships its parts
|
|
3
3
|
beside the type they share. */
|
|
4
4
|
import { Button, Notice, Stack, Text } from '@wordpress/ui';
|
|
5
|
+
import { createContext, useContext } from 'react';
|
|
6
|
+
/** The level of the title of the Page around a section title, 1 outside any Page. */
|
|
7
|
+
const PageLevelContext = createContext(1);
|
|
8
|
+
/**
|
|
9
|
+
* Returns the heading element of a level.
|
|
10
|
+
* @param level - The heading level, 1 to 4.
|
|
11
|
+
* @returns The element name.
|
|
12
|
+
*/
|
|
13
|
+
function headingTag(level) {
|
|
14
|
+
return `h${level}`;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Returns the heading element one level under the title of the Page around it, an h2 outside any Page.
|
|
18
|
+
* @returns The element name.
|
|
19
|
+
*/
|
|
20
|
+
export function useHeadingUnderPage() {
|
|
21
|
+
return headingTag(useContext(PageLevelContext) + 1);
|
|
22
|
+
}
|
|
5
23
|
/**
|
|
6
24
|
* Renders a screen's title as the page heading.
|
|
7
|
-
* @param props - The title text
|
|
25
|
+
* @param props - The title text, the type scale to render it at and its heading level, 1 when absent.
|
|
8
26
|
* @returns The page title element.
|
|
9
27
|
*/
|
|
10
|
-
export function PageTitle({ children, variant = 'heading-lg', }) {
|
|
11
|
-
|
|
28
|
+
export function PageTitle({ children, variant = 'heading-lg', level = 1, }) {
|
|
29
|
+
const Heading = headingTag(level);
|
|
30
|
+
return (_jsx(Text, { variant: variant, render: _jsx(Heading, {}), children: children }));
|
|
12
31
|
}
|
|
13
32
|
/**
|
|
14
|
-
* Renders a section heading one size step above the field labels.
|
|
15
|
-
* @param props - The heading text, its level, and the id and tab index a screen moves
|
|
33
|
+
* Renders a section heading one size step above the field labels, one level deeper inside a level 2 Page.
|
|
34
|
+
* @param props - The heading text, its rank under a level 1 page title, and the id and tab index a screen moves
|
|
35
|
+
* focus with.
|
|
16
36
|
* @returns The section heading element.
|
|
17
37
|
*/
|
|
18
38
|
export function SectionTitle({ children, level = 2, id, tabIndex, }) {
|
|
19
|
-
const
|
|
20
|
-
|
|
39
|
+
const pageLevel = useContext(PageLevelContext);
|
|
40
|
+
const Heading = headingTag(level + pageLevel - 1);
|
|
41
|
+
return (_jsx(Text, { variant: level === 2 ? 'heading-lg' : 'heading-md', render: _jsx(Heading, {}), id: id, tabIndex: tabIndex, children: children }));
|
|
21
42
|
}
|
|
22
43
|
/**
|
|
23
44
|
* Returns the props that let code focus a list with a name or a ref, and name a list region given a label.
|
|
@@ -31,12 +52,13 @@ function regionOf(label, reached) {
|
|
|
31
52
|
}
|
|
32
53
|
/**
|
|
33
54
|
* Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
|
|
34
|
-
* @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class
|
|
55
|
+
* @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
|
|
56
|
+
* and content.
|
|
35
57
|
* @returns The page element.
|
|
36
58
|
*/
|
|
37
|
-
export function Page({ title, subtitle, actions, tabs, aside, list = false, listLabel, listRef, className, children, }) {
|
|
59
|
+
export function Page({ title, subtitle, actions, tabs, aside, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
|
|
38
60
|
const classes = className === undefined ? 'godmin-page' : `godmin-page ${className}`;
|
|
39
|
-
return (_jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageTitle, { children: title }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, children: list ? (_jsx("div", { className: "godmin-page__list", ref: listRef, ...regionOf(listLabel, listRef !== undefined), children: children })) : (children) })] }));
|
|
61
|
+
return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageTitle, { level: headingLevel, children: title }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, children: list ? (_jsx("div", { className: "godmin-page__list", ref: listRef, ...regionOf(listLabel, listRef !== undefined), children: children })) : (children) })] }) }));
|
|
40
62
|
}
|
|
41
63
|
/**
|
|
42
64
|
* Renders a page's content, beside its aside when it has one.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { AnyRouter, StaticDataRouteOption, ToOptions } from '@tanstack/react-router';
|
|
2
|
+
/** Where a row goes, as a TanStack Link names it: to, with its params, search and hash. */
|
|
3
|
+
export type RowAddress = Pick<ToOptions, 'to' | 'from' | 'params' | 'search' | 'hash'>;
|
|
4
|
+
/** A matched route as the sidebar reads it. */
|
|
5
|
+
export interface SidebarMatch {
|
|
6
|
+
/** The id of the route. */
|
|
7
|
+
routeId: string;
|
|
8
|
+
/** The static data the route declares. */
|
|
9
|
+
staticData: StaticDataRouteOption;
|
|
10
|
+
}
|
|
11
|
+
/** What the routes an address opens declare. */
|
|
12
|
+
interface AddressRoutes {
|
|
13
|
+
/** The id of the deepest route that declares a Sidebar, undefined when none does. */
|
|
14
|
+
drilldownParent: string | undefined;
|
|
15
|
+
/** The capability of every route the address opens, outermost first. */
|
|
16
|
+
capabilities: readonly string[];
|
|
17
|
+
}
|
|
18
|
+
/** Where a row goes and what the routes it opens declare. */
|
|
19
|
+
export interface RowRoutes extends AddressRoutes {
|
|
20
|
+
/** The href the router builds for the address, its hash included. */
|
|
21
|
+
href: string;
|
|
22
|
+
/** The pathname and search of the address, the form a frame watches its location in. */
|
|
23
|
+
address: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Finds the deepest match whose route declares a Sidebar.
|
|
27
|
+
* @param matches - The matched routes, outermost first.
|
|
28
|
+
* @returns That match, or undefined when no route declares one.
|
|
29
|
+
*/
|
|
30
|
+
export declare function findSidebarMatch<T extends SidebarMatch>(matches: readonly T[]): T | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Returns the pathname and search of a location, the form a frame watches its location in.
|
|
33
|
+
* @param location - The location.
|
|
34
|
+
* @returns The pathname followed by the search.
|
|
35
|
+
*/
|
|
36
|
+
export declare function locationAddress(location: {
|
|
37
|
+
pathname: string;
|
|
38
|
+
searchStr: string;
|
|
39
|
+
}): string;
|
|
40
|
+
/**
|
|
41
|
+
* Finds where a row goes and what the routes it opens declare, once per address and location.
|
|
42
|
+
* @param router - The router the address resolves on.
|
|
43
|
+
* @param address - Where the row goes.
|
|
44
|
+
* @returns The row, with no route for an address that leaves the site.
|
|
45
|
+
*/
|
|
46
|
+
export declare function findRowRoutes(router: AnyRouter, address: RowAddress): RowRoutes;
|
|
47
|
+
/**
|
|
48
|
+
* Finds the sub menu screen a row's address opens, the deepest route it matches that declares a Sidebar.
|
|
49
|
+
* @param router - The router the address resolves on.
|
|
50
|
+
* @param address - Where the row goes.
|
|
51
|
+
* @returns That route's id, or undefined when no route declares one or the address leaves the site.
|
|
52
|
+
*/
|
|
53
|
+
export declare function findDrilldownParent(router: AnyRouter, address: RowAddress): string | undefined;
|
|
54
|
+
/**
|
|
55
|
+
* Returns the capability of every route a row's address opens, parents included.
|
|
56
|
+
* @param router - The router the address resolves on.
|
|
57
|
+
* @param address - Where the row goes.
|
|
58
|
+
* @returns The capabilities, outermost route first, none when the address leaves the site.
|
|
59
|
+
*/
|
|
60
|
+
export declare function findRouteCapabilities(router: AnyRouter, address: RowAddress): readonly string[];
|
|
61
|
+
/**
|
|
62
|
+
* Finds the pathname and search a link moves the reader to.
|
|
63
|
+
* @param router - The router the address resolves on.
|
|
64
|
+
* @param address - Where the link goes.
|
|
65
|
+
* @returns That address, or undefined when it is the one already open.
|
|
66
|
+
*/
|
|
67
|
+
export declare function findMoveTarget(router: AnyRouter, address: RowAddress): string | undefined;
|
|
68
|
+
export {};
|