@gopherium/godmin 0.1.3 → 0.2.1
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 +131 -6
- package/dist/base.css +158 -0
- package/dist/breakpoints.d.ts +12 -0
- package/dist/breakpoints.js +12 -0
- package/dist/frame.d.ts +50 -0
- package/dist/frame.js +67 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +6 -0
- package/dist/nav-screen.d.ts +17 -0
- package/dist/nav-screen.js +31 -0
- package/dist/page.d.ts +50 -0
- package/dist/page.js +42 -0
- package/dist/router.d.ts +16 -0
- package/dist/router.js +20 -0
- package/dist/testing.d.ts +7 -0
- package/dist/testing.js +74 -11
- package/dist/toaster.d.ts +23 -0
- package/dist/toaster.js +62 -0
- package/dist/use-media-query.d.ts +6 -0
- package/dist/use-media-query.js +16 -0
- package/package.json +11 -1
package/README.md
CHANGED
|
@@ -19,18 +19,26 @@ here duplicates something upstream ships.
|
|
|
19
19
|
|
|
20
20
|
| Entry point | Contents |
|
|
21
21
|
| --- | --- |
|
|
22
|
-
| `@gopherium/godmin` | `AdminRoot`, `useTokenDocument`, `SUPPORTED_WPDS` |
|
|
23
|
-
| `@gopherium/godmin/base.css` | cascade layer order, design tokens, host rules |
|
|
24
|
-
| `@gopherium/godmin/
|
|
22
|
+
| `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `NavScreen`, `ErrorNotice`, `LoadMore`, `Toaster`, `useToaster`, `useMediaQuery`, `useTokenDocument`, the breakpoints, `SUPPORTED_WPDS` |
|
|
23
|
+
| `@gopherium/godmin/base.css` | cascade layer order, design tokens, host rules, frame and screen styles |
|
|
24
|
+
| `@gopherium/godmin/router` | `useCanvas`, `useFrameLocation`, the `canvas` route static data |
|
|
25
|
+
| `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport`, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR` |
|
|
25
26
|
| `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy` |
|
|
26
27
|
| `@gopherium/godmin/stylelint` | the design system stylelint rules |
|
|
27
28
|
| `@gopherium/godmin/patches` | the React 19 patch for `@wordpress/element`, temporary |
|
|
28
29
|
|
|
29
30
|
## Status
|
|
30
31
|
|
|
31
|
-
Version 0.1.
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
Version 0.1.x was the host layer alone. The frame was held back while
|
|
33
|
+
`@wordpress/admin-ui` built its own page chrome, and shipped in 0.2.0 once two
|
|
34
|
+
applications had run the same shell long enough to settle its shape. Waiting
|
|
35
|
+
was worth it: the width, the empty state placement, the narrow viewport shell
|
|
36
|
+
and the table region all changed during that time, and each would have been a
|
|
37
|
+
breaking release had the frame gone out first.
|
|
38
|
+
|
|
39
|
+
`@wordpress/admin-ui` remains the thing to watch. GodMin does not wrap it,
|
|
40
|
+
because a kit that wraps an API still moving adds a release hop to every
|
|
41
|
+
upstream fix. See the CHANGELOG for what each release adds.
|
|
34
42
|
|
|
35
43
|
## Install
|
|
36
44
|
|
|
@@ -78,6 +86,96 @@ If you declare your own layers, name GodMin's in the order you want:
|
|
|
78
86
|
@layer wp-ui, godmin, my-app;
|
|
79
87
|
```
|
|
80
88
|
|
|
89
|
+
## Framing the application
|
|
90
|
+
|
|
91
|
+
`Frame` builds the shell out of the regions you render. A region exists because
|
|
92
|
+
its element is there, not because a flag says so, so an application with no
|
|
93
|
+
rail simply does not render one.
|
|
94
|
+
|
|
95
|
+
```tsx
|
|
96
|
+
<Frame.Root location={pathname}>
|
|
97
|
+
<Frame.Rail brand={<HomeLink />}>
|
|
98
|
+
<YourNavigation />
|
|
99
|
+
</Frame.Rail>
|
|
100
|
+
<Frame.Canvas canvas={mode}>
|
|
101
|
+
<YourScreen />
|
|
102
|
+
</Frame.Canvas>
|
|
103
|
+
</Frame.Root>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Below 1024px the rail leaves and the same children appear in a drawer behind a
|
|
107
|
+
menu button, so you write your navigation once. Below 640px the canvas meets
|
|
108
|
+
the screen edges and pads tighter.
|
|
109
|
+
|
|
110
|
+
The core imports no router. `Frame.Root` takes `location` as a plain string and
|
|
111
|
+
closes the drawer whenever it changes, which means any link closes it, including
|
|
112
|
+
links a plugin added. `chromeColor` and `canvasColor` theme the two regions.
|
|
113
|
+
|
|
114
|
+
`brand` is rendered as given and should not be a heading. Each screen owns the
|
|
115
|
+
one first level heading on the page, and `Page` renders it.
|
|
116
|
+
|
|
117
|
+
### Screens
|
|
118
|
+
|
|
119
|
+
`Page` puts the title top left, an optional subtitle under it and optional
|
|
120
|
+
actions top right.
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
<Page title="Reports" actions={<Button>New report</Button>}>
|
|
124
|
+
<ReportTable />
|
|
125
|
+
</Page>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
A screen that fills the canvas edge to edge builds its own chrome and uses
|
|
129
|
+
`PageTitle` directly, so it still carries exactly one first level heading.
|
|
130
|
+
`NavScreen` renders a drill-down layer, taking the way back as an element you
|
|
131
|
+
supply so the kit stays router free.
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
<NavScreen title="Conversations" back={<Link to="/" />}>
|
|
135
|
+
<ConversationList />
|
|
136
|
+
</NavScreen>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`base.css` also ships `godmin-empty`, `godmin-form`, `godmin-table` and
|
|
140
|
+
`godmin-table-scroll`. The last two go together: a table wider than a phone
|
|
141
|
+
scrolls inside its own region rather than dragging the page sideways.
|
|
142
|
+
|
|
143
|
+
```tsx
|
|
144
|
+
<div className="godmin-table-scroll" role="region" aria-label="Reports" tabIndex={0}>
|
|
145
|
+
<table className="godmin-table">…</table>
|
|
146
|
+
</div>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The region is focusable so a keyboard can reach the columns that scrolled out
|
|
150
|
+
of view, and it establishes a containing block, without which absolutely
|
|
151
|
+
positioned content inside it escapes the clip and widens the document.
|
|
152
|
+
|
|
153
|
+
### Reading the canvas from routes
|
|
154
|
+
|
|
155
|
+
With TanStack Router, `@gopherium/godmin/router` lets a route declare how it
|
|
156
|
+
fills the canvas, and the deepest route that declares one wins, so a child can
|
|
157
|
+
opt back to a padded canvas its section left behind.
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
createRoute({ path: 'threads/$id', staticData: { canvas: 'bleed' } })
|
|
161
|
+
|
|
162
|
+
const mode = useCanvas()
|
|
163
|
+
const pathname = useFrameLocation()
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Raising messages
|
|
167
|
+
|
|
168
|
+
`Toaster` holds messages a screen raises, each with an optional action.
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
171
|
+
<Toaster>
|
|
172
|
+
<YourApp />
|
|
173
|
+
</Toaster>
|
|
174
|
+
|
|
175
|
+
const toaster = useToaster()
|
|
176
|
+
toaster.show('Post moved to trash', { label: 'Undo', onAct: restore })
|
|
177
|
+
```
|
|
178
|
+
|
|
81
179
|
### Rendering into an iframe
|
|
82
180
|
|
|
83
181
|
Design system styles are injected per document, so a secondary document such as
|
|
@@ -119,6 +217,19 @@ expect(getAnnouncement()).toBe('Draft saved')
|
|
|
119
217
|
`renderAdmin` renders a tree inside `AdminRoot`, so components that read design
|
|
120
218
|
tokens behave as they will in the application.
|
|
121
219
|
|
|
220
|
+
A test runner evaluates no media queries, so `setViewport` says what they
|
|
221
|
+
should report and tells any listener the viewport changed. That is how a test
|
|
222
|
+
renders the narrow shell.
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import { setViewport } from '@gopherium/godmin/testing'
|
|
226
|
+
|
|
227
|
+
setViewport({ matches: true })
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
It resets before the next test, along with the rendered tree, which a runner
|
|
231
|
+
without globals never clears by itself.
|
|
232
|
+
|
|
122
233
|
`@testing-library/react` and `vitest` are optional peers, needed only for this
|
|
123
234
|
entry point.
|
|
124
235
|
|
|
@@ -141,6 +252,20 @@ export default defineConfig({
|
|
|
141
252
|
The list cannot live in the package alone, because `resolve.dedupe` is read
|
|
142
253
|
from your own config, so GodMin ships it as data for you to spread.
|
|
143
254
|
|
|
255
|
+
Dedupe settles which copy your bundler picks, but it cannot stop a second one
|
|
256
|
+
being installed. `@wordpress/element` up to 8.4.0 declares React 18 as a
|
|
257
|
+
dependency rather than a peer, so a fresh install materialises React 18 beside
|
|
258
|
+
your React 19 and the first hook throws `Cannot read properties of null`. Pin
|
|
259
|
+
the version yourself.
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{
|
|
263
|
+
"pnpm": {
|
|
264
|
+
"overrides": { "react": "^19.2.0", "react-dom": "^19.2.0" }
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
144
269
|
## React 19 and @wordpress/element
|
|
145
270
|
|
|
146
271
|
Up to and including 8.4.0, `@wordpress/element` imports APIs that React 19
|
package/dist/base.css
CHANGED
|
@@ -20,3 +20,161 @@ body {
|
|
|
20
20
|
background: var(--wpds-color-background-surface-neutral);
|
|
21
21
|
}
|
|
22
22
|
}
|
|
23
|
+
|
|
24
|
+
@layer godmin {
|
|
25
|
+
.godmin-layout {
|
|
26
|
+
display: flex;
|
|
27
|
+
height: 100vh;
|
|
28
|
+
background: var(--wpds-color-background-surface-neutral-weak);
|
|
29
|
+
color: var(--wpds-color-foreground-content-neutral);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
.godmin-layout--small {
|
|
33
|
+
flex-direction: column;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
.godmin-layout__rail {
|
|
37
|
+
display: flex;
|
|
38
|
+
flex-direction: column;
|
|
39
|
+
flex-shrink: 0;
|
|
40
|
+
width: 300px;
|
|
41
|
+
padding: 16px;
|
|
42
|
+
box-sizing: border-box;
|
|
43
|
+
overflow-y: auto;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
.godmin-layout__topbar {
|
|
47
|
+
display: flex;
|
|
48
|
+
flex-shrink: 0;
|
|
49
|
+
align-items: center;
|
|
50
|
+
gap: 8px;
|
|
51
|
+
padding: 8px 16px;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
.godmin-layout__drawer {
|
|
55
|
+
display: flex;
|
|
56
|
+
flex-direction: column;
|
|
57
|
+
padding: 16px;
|
|
58
|
+
box-sizing: border-box;
|
|
59
|
+
overflow-y: auto;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
.godmin-layout__canvas {
|
|
63
|
+
display: flex;
|
|
64
|
+
flex-direction: column;
|
|
65
|
+
flex: 1;
|
|
66
|
+
min-width: 0;
|
|
67
|
+
margin: 16px;
|
|
68
|
+
padding: 24px;
|
|
69
|
+
box-sizing: border-box;
|
|
70
|
+
border-radius: var(--wpds-border-radius-xl);
|
|
71
|
+
background: var(--wpds-color-background-surface-neutral);
|
|
72
|
+
color: var(--wpds-color-foreground-content-neutral);
|
|
73
|
+
box-shadow: 0 1px 2px rgb(0 0 0 / 0.08);
|
|
74
|
+
overflow-x: hidden;
|
|
75
|
+
overflow-y: auto;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
.godmin-layout__canvas--bleed {
|
|
79
|
+
padding: 0;
|
|
80
|
+
overflow: hidden;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
.godmin-toasts {
|
|
84
|
+
position: fixed;
|
|
85
|
+
left: 16px;
|
|
86
|
+
bottom: 16px;
|
|
87
|
+
z-index: 1;
|
|
88
|
+
max-width: calc(100vw - 32px);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
.godmin-nav-screen__title {
|
|
92
|
+
flex: 1;
|
|
93
|
+
min-width: 0;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
.godmin-nav-screen__title:focus {
|
|
97
|
+
outline: none;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
.godmin-nav-screen__back {
|
|
101
|
+
display: inline-flex;
|
|
102
|
+
color: inherit;
|
|
103
|
+
border-radius: var(--wpds-border-radius-md);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.godmin-nav-screen__back:focus-visible {
|
|
107
|
+
outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
|
|
108
|
+
outline-offset: 2px;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
.godmin-nav-screen__description {
|
|
112
|
+
color: var(--wpds-color-foreground-content-neutral-weak);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
.godmin-page__subtitle {
|
|
116
|
+
color: var(--wpds-color-foreground-content-neutral-weak);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
.godmin-form {
|
|
120
|
+
display: flex;
|
|
121
|
+
flex-direction: column;
|
|
122
|
+
gap: var(--wpds-dimension-gap-md);
|
|
123
|
+
max-width: var(--wpds-dimension-surface-width-sm);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
.godmin-empty {
|
|
127
|
+
margin-inline: auto;
|
|
128
|
+
padding-block: 48px;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
.godmin-table {
|
|
132
|
+
width: 100%;
|
|
133
|
+
border-collapse: collapse;
|
|
134
|
+
text-align: left;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
.godmin-table th,
|
|
138
|
+
.godmin-table td {
|
|
139
|
+
padding: 8px 12px;
|
|
140
|
+
border-bottom: 1px solid var(--wpds-color-stroke-surface-neutral);
|
|
141
|
+
vertical-align: middle;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
.godmin-table th {
|
|
145
|
+
font-size: var(--wpds-typography-font-size-sm);
|
|
146
|
+
color: var(--wpds-color-foreground-content-neutral-weak);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
.godmin-table__actions {
|
|
150
|
+
width: 1%;
|
|
151
|
+
white-space: nowrap;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/* Small viewport overrides live together at the end of the sheet, so they
|
|
155
|
+
always win over the rules above them without extra specificity. */
|
|
156
|
+
@media (max-width: 639px) {
|
|
157
|
+
.godmin-layout__canvas {
|
|
158
|
+
margin: 0;
|
|
159
|
+
padding: 16px;
|
|
160
|
+
border-radius: 0;
|
|
161
|
+
box-shadow: none;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
.godmin-layout__canvas--bleed {
|
|
165
|
+
padding: 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/* The region needs a containing block, or absolutely positioned content
|
|
169
|
+
inside it escapes the clip and widens the document. */
|
|
170
|
+
.godmin-table-scroll {
|
|
171
|
+
position: relative;
|
|
172
|
+
overflow-x: auto;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
.godmin-table-scroll:focus-visible {
|
|
176
|
+
outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus);
|
|
177
|
+
outline-offset: 2px;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The viewport width below which the rail becomes a drawer.
|
|
3
|
+
*/
|
|
4
|
+
export declare const RAIL_BREAKPOINT = 1024;
|
|
5
|
+
/**
|
|
6
|
+
* The viewport width below which the canvas meets the screen edges.
|
|
7
|
+
*/
|
|
8
|
+
export declare const DENSE_BREAKPOINT = 640;
|
|
9
|
+
/**
|
|
10
|
+
* The media query the frame folds its rail at.
|
|
11
|
+
*/
|
|
12
|
+
export declare const SMALL_VIEWPORT = "(max-width: 1023px)";
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The viewport width below which the rail becomes a drawer.
|
|
3
|
+
*/
|
|
4
|
+
export const RAIL_BREAKPOINT = 1024;
|
|
5
|
+
/**
|
|
6
|
+
* The viewport width below which the canvas meets the screen edges.
|
|
7
|
+
*/
|
|
8
|
+
export const DENSE_BREAKPOINT = 640;
|
|
9
|
+
/**
|
|
10
|
+
* The media query the frame folds its rail at.
|
|
11
|
+
*/
|
|
12
|
+
export const SMALL_VIEWPORT = `(max-width: ${RAIL_BREAKPOINT - 1}px)`;
|
package/dist/frame.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { ThemeProvider } from '@wordpress/theme';
|
|
2
|
+
import type { ComponentProps, ReactNode } from 'react';
|
|
3
|
+
type ThemeColor = ComponentProps<typeof ThemeProvider>['color'];
|
|
4
|
+
export interface FrameRootProps {
|
|
5
|
+
children: ReactNode;
|
|
6
|
+
location?: string;
|
|
7
|
+
chromeColor?: ThemeColor;
|
|
8
|
+
canvasColor?: ThemeColor;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Frames an admin application, folding its rail away on a narrow viewport.
|
|
12
|
+
* @param props - The regions, the current location, and the region colors.
|
|
13
|
+
* @returns The frame element.
|
|
14
|
+
*/
|
|
15
|
+
declare function Root({ children, location, chromeColor, canvasColor }: FrameRootProps): import("react").JSX.Element;
|
|
16
|
+
export interface FrameRailProps {
|
|
17
|
+
children: ReactNode;
|
|
18
|
+
brand?: ReactNode;
|
|
19
|
+
menuLabel?: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Renders the navigation region, as a rail when there is room and as a top bar
|
|
23
|
+
* with a drawer when there is not.
|
|
24
|
+
* @param props - The rail content, the brand, and the menu button label.
|
|
25
|
+
* @returns The rail element.
|
|
26
|
+
*/
|
|
27
|
+
declare function Rail({ children, brand, menuLabel }: FrameRailProps): import("react").JSX.Element;
|
|
28
|
+
/**
|
|
29
|
+
* How a screen fills its canvas region.
|
|
30
|
+
*/
|
|
31
|
+
export type CanvasMode = 'padded' | 'bleed';
|
|
32
|
+
export interface FrameCanvasProps {
|
|
33
|
+
children: ReactNode;
|
|
34
|
+
canvas?: CanvasMode;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Renders the region showing the active screen.
|
|
38
|
+
* @param props - The screen, and whether it fills the canvas edge to edge.
|
|
39
|
+
* @returns The canvas element.
|
|
40
|
+
*/
|
|
41
|
+
declare function Canvas({ children, canvas }: FrameCanvasProps): import("react").JSX.Element;
|
|
42
|
+
/**
|
|
43
|
+
* The admin frame, whose regions are present when their element is rendered.
|
|
44
|
+
*/
|
|
45
|
+
export declare const Frame: {
|
|
46
|
+
Root: typeof Root;
|
|
47
|
+
Rail: typeof Rail;
|
|
48
|
+
Canvas: typeof Canvas;
|
|
49
|
+
};
|
|
50
|
+
export {};
|
package/dist/frame.js
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
+
/* oxlint-disable react/only-export-components -- a compound component is an
|
|
3
|
+
object export standing beside the parts it is built from. */
|
|
4
|
+
import { ThemeProvider } from '@wordpress/theme';
|
|
5
|
+
import { Drawer, IconButton, VisuallyHidden } from '@wordpress/ui';
|
|
6
|
+
import { createContext, useContext, useEffect, useState } from 'react';
|
|
7
|
+
import { SMALL_VIEWPORT } from './breakpoints.js';
|
|
8
|
+
import { useMediaQuery } from './use-media-query.js';
|
|
9
|
+
/**
|
|
10
|
+
* The glyph on the button that opens the rail drawer.
|
|
11
|
+
*/
|
|
12
|
+
const menuIcon = (_jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M5 5v1.5h14V5H5zm0 7.8h14v-1.5H5v1.5zM5 19h14v-1.5H5V19z" }) }));
|
|
13
|
+
const FrameContext = createContext({ small: false, location: undefined });
|
|
14
|
+
/**
|
|
15
|
+
* Frames an admin application, folding its rail away on a narrow viewport.
|
|
16
|
+
* @param props - The regions, the current location, and the region colors.
|
|
17
|
+
* @returns The frame element.
|
|
18
|
+
*/
|
|
19
|
+
function Root({ children, location, chromeColor, canvasColor }) {
|
|
20
|
+
const small = useMediaQuery(SMALL_VIEWPORT);
|
|
21
|
+
const classes = small ? 'godmin-layout godmin-layout--small' : 'godmin-layout';
|
|
22
|
+
return (_jsx(ThemeProvider, { color: chromeColor, children: _jsx(FrameContext.Provider, { value: { small, location }, children: _jsx("div", { className: classes, children: _jsx(CanvasColorContext.Provider, { value: canvasColor, children: children }) }) }) }));
|
|
23
|
+
}
|
|
24
|
+
const CanvasColorContext = createContext(undefined);
|
|
25
|
+
/**
|
|
26
|
+
* Renders the navigation region, as a rail when there is room and as a top bar
|
|
27
|
+
* with a drawer when there is not.
|
|
28
|
+
* @param props - The rail content, the brand, and the menu button label.
|
|
29
|
+
* @returns The rail element.
|
|
30
|
+
*/
|
|
31
|
+
function Rail({ children, brand, menuLabel = 'Open navigation' }) {
|
|
32
|
+
const { small } = useContext(FrameContext);
|
|
33
|
+
if (!small) {
|
|
34
|
+
return _jsx("div", { className: "godmin-layout__rail", children: children });
|
|
35
|
+
}
|
|
36
|
+
return (_jsx(TopBar, { brand: brand, menuLabel: menuLabel, children: children }));
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Renders the narrow viewport chrome: a menu button opening the rail content in
|
|
40
|
+
* a drawer, beside the brand.
|
|
41
|
+
* @param props - The rail content, the brand, and the menu button label.
|
|
42
|
+
* @returns The top bar element.
|
|
43
|
+
*/
|
|
44
|
+
function TopBar({ children, brand, menuLabel }) {
|
|
45
|
+
const { location } = useContext(FrameContext);
|
|
46
|
+
const [open, setOpen] = useState(false);
|
|
47
|
+
useEffect(() => {
|
|
48
|
+
setOpen(false);
|
|
49
|
+
}, [location]);
|
|
50
|
+
return (_jsxs("div", { className: "godmin-layout__topbar", children: [_jsxs(Drawer.Root, { open: open, onOpenChange: setOpen, children: [_jsx(Drawer.Trigger, { render: _jsx(IconButton, { icon: menuIcon, label: menuLabel }) }), _jsxs(Drawer.Popup, { className: "godmin-layout__drawer", children: [_jsx(VisuallyHidden, { render: _jsx(Drawer.Title, {}), children: menuLabel }), children] })] }), brand] }));
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Renders the region showing the active screen.
|
|
54
|
+
* @param props - The screen, and whether it fills the canvas edge to edge.
|
|
55
|
+
* @returns The canvas element.
|
|
56
|
+
*/
|
|
57
|
+
function Canvas({ children, canvas = 'padded' }) {
|
|
58
|
+
const color = useContext(CanvasColorContext);
|
|
59
|
+
const classes = canvas === 'bleed'
|
|
60
|
+
? 'godmin-layout__canvas godmin-layout__canvas--bleed'
|
|
61
|
+
: 'godmin-layout__canvas';
|
|
62
|
+
return (_jsx(ThemeProvider, { color: color, children: _jsx("main", { className: classes, children: children }) }));
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The admin frame, whose regions are present when their element is rendered.
|
|
66
|
+
*/
|
|
67
|
+
export const Frame = { Root, Rail, Canvas };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
export { AdminRoot } from './admin-root.js';
|
|
2
2
|
export type { AdminRootProps } from './admin-root.js';
|
|
3
|
+
export { DENSE_BREAKPOINT, RAIL_BREAKPOINT, SMALL_VIEWPORT } from './breakpoints.js';
|
|
4
|
+
export { Frame } from './frame.js';
|
|
5
|
+
export type { CanvasMode, FrameCanvasProps, FrameRailProps, FrameRootProps, } from './frame.js';
|
|
6
|
+
export { NavScreen } from './nav-screen.js';
|
|
7
|
+
export type { NavScreenProps } from './nav-screen.js';
|
|
8
|
+
export { ErrorNotice, LoadMore, Page, PageTitle } from './page.js';
|
|
9
|
+
export type { LoadMoreQuery, PageProps } from './page.js';
|
|
10
|
+
export { Toaster, useToaster } from './toaster.js';
|
|
11
|
+
export type { ToastAction, ToasterHandle, ToasterProps } from './toaster.js';
|
|
12
|
+
export { useMediaQuery } from './use-media-query.js';
|
|
3
13
|
export { useTokenDocument } from './use-token-document.js';
|
|
4
14
|
/**
|
|
5
15
|
* The design system version window this build was tested against.
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
// SPDX-License-Identifier: Apache-2.0
|
|
2
2
|
export { AdminRoot } from './admin-root.js';
|
|
3
|
+
export { DENSE_BREAKPOINT, RAIL_BREAKPOINT, SMALL_VIEWPORT } from './breakpoints.js';
|
|
4
|
+
export { Frame } from './frame.js';
|
|
5
|
+
export { NavScreen } from './nav-screen.js';
|
|
6
|
+
export { ErrorNotice, LoadMore, Page, PageTitle } from './page.js';
|
|
7
|
+
export { Toaster, useToaster } from './toaster.js';
|
|
8
|
+
export { useMediaQuery } from './use-media-query.js';
|
|
3
9
|
export { useTokenDocument } from './use-token-document.js';
|
|
4
10
|
/**
|
|
5
11
|
* The design system version window this build was tested against.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { ReactElement, ReactNode } from 'react';
|
|
2
|
+
export interface NavScreenProps {
|
|
3
|
+
title: string;
|
|
4
|
+
back?: ReactElement<Record<string, unknown>>;
|
|
5
|
+
backLabel?: string;
|
|
6
|
+
description?: ReactNode;
|
|
7
|
+
actions?: ReactNode;
|
|
8
|
+
footer?: ReactNode;
|
|
9
|
+
children: ReactNode;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Renders a drill-down navigation screen: a way back to the parent layer, the
|
|
13
|
+
* title, optional description and actions, the content, and an optional footer.
|
|
14
|
+
* @param props - The title, the back affordance and label, and the regions.
|
|
15
|
+
* @returns The navigation screen element.
|
|
16
|
+
*/
|
|
17
|
+
export declare function NavScreen({ title, back, backLabel, description, actions, footer, children, }: NavScreenProps): import("react").JSX.Element;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
+
import { Icon, Link, Stack, Text } from '@wordpress/ui';
|
|
3
|
+
import { useEffect, useRef } from 'react';
|
|
4
|
+
/**
|
|
5
|
+
* The glyph on the affordance returning to the parent layer.
|
|
6
|
+
*/
|
|
7
|
+
const chevronLeft = (_jsx("svg", { viewBox: "0 0 24 24", xmlns: "http://www.w3.org/2000/svg", fill: "currentColor", children: _jsx("path", { d: "M14.6 7l-1.2-1L8 12l5.4 6 1.2-1-4.6-5z" }) }));
|
|
8
|
+
/**
|
|
9
|
+
* Renders a region in its own element, or nothing when a screen gives none.
|
|
10
|
+
* @param props - The region content and the class naming it.
|
|
11
|
+
* @returns The region element, or null.
|
|
12
|
+
*/
|
|
13
|
+
function Region({ content, className }) {
|
|
14
|
+
if (content === undefined) {
|
|
15
|
+
return null;
|
|
16
|
+
}
|
|
17
|
+
return _jsx("div", { className: className, children: content });
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Renders a drill-down navigation screen: a way back to the parent layer, the
|
|
21
|
+
* title, optional description and actions, the content, and an optional footer.
|
|
22
|
+
* @param props - The title, the back affordance and label, and the regions.
|
|
23
|
+
* @returns The navigation screen element.
|
|
24
|
+
*/
|
|
25
|
+
export function NavScreen({ title, back, backLabel = 'Back', description, actions, footer, children, }) {
|
|
26
|
+
const titleRef = useRef(null);
|
|
27
|
+
useEffect(() => {
|
|
28
|
+
titleRef.current?.focus();
|
|
29
|
+
}, []);
|
|
30
|
+
return (_jsxs(Stack, { direction: "column", gap: "md", className: "godmin-nav-screen", children: [_jsxs(Stack, { direction: "row", align: "flex-start", gap: "sm", children: [back !== undefined && (_jsx(Link, { render: back, "aria-label": backLabel, className: "godmin-nav-screen__back", children: _jsx(Icon, { icon: chevronLeft, size: 24, "aria-hidden": true }) })), _jsx(Text, { ref: titleRef, variant: "heading-md", render: _jsx("h2", { tabIndex: -1 }), className: "godmin-nav-screen__title", children: title }), _jsx(Region, { content: actions, className: "godmin-nav-screen__actions" })] }), _jsxs(Stack, { direction: "column", gap: "sm", children: [_jsx(Region, { content: description, className: "godmin-nav-screen__description" }), children] }), _jsx(Region, { content: footer, className: "godmin-nav-screen__footer" })] }));
|
|
31
|
+
}
|
package/dist/page.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { Text } from '@wordpress/ui';
|
|
2
|
+
import type { ComponentProps, ReactNode } from 'react';
|
|
3
|
+
type TextVariant = ComponentProps<typeof Text>['variant'];
|
|
4
|
+
/**
|
|
5
|
+
* Renders a screen's title as the page heading.
|
|
6
|
+
* @param props - The title text and the type scale to render it at.
|
|
7
|
+
* @returns The page title element.
|
|
8
|
+
*/
|
|
9
|
+
export declare function PageTitle({ children, variant, }: {
|
|
10
|
+
children: ReactNode;
|
|
11
|
+
variant?: TextVariant;
|
|
12
|
+
}): import("react").JSX.Element;
|
|
13
|
+
export interface PageProps {
|
|
14
|
+
title: string;
|
|
15
|
+
subtitle?: string;
|
|
16
|
+
actions?: ReactNode;
|
|
17
|
+
className?: string;
|
|
18
|
+
children: ReactNode;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Renders a screen: its title top left, an optional subtitle under it,
|
|
22
|
+
* optional actions top right, and the content below.
|
|
23
|
+
* @param props - The title, subtitle, actions, extra class and content.
|
|
24
|
+
* @returns The page element.
|
|
25
|
+
*/
|
|
26
|
+
export declare function Page({ title, subtitle, actions, className, children }: PageProps): import("react").JSX.Element;
|
|
27
|
+
/**
|
|
28
|
+
* Renders a failure message that a screen reader announces.
|
|
29
|
+
* @param props - The message to announce.
|
|
30
|
+
* @returns The error notice element.
|
|
31
|
+
*/
|
|
32
|
+
export declare function ErrorNotice({ children }: {
|
|
33
|
+
children: ReactNode;
|
|
34
|
+
}): import("react").JSX.Element;
|
|
35
|
+
export interface LoadMoreQuery {
|
|
36
|
+
hasNextPage: boolean;
|
|
37
|
+
isFetchingNextPage: boolean;
|
|
38
|
+
fetchNextPage: () => Promise<unknown>;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Renders the cursor pagination button for an infinite query, or nothing once
|
|
42
|
+
* every page is loaded.
|
|
43
|
+
* @param props - The query to page through and the button label.
|
|
44
|
+
* @returns The load more button, or null.
|
|
45
|
+
*/
|
|
46
|
+
export declare function LoadMore({ query, children }: {
|
|
47
|
+
query: LoadMoreQuery;
|
|
48
|
+
children: ReactNode;
|
|
49
|
+
}): import("react").JSX.Element | null;
|
|
50
|
+
export {};
|
package/dist/page.js
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
+
/* oxlint-disable react/only-export-components -- the page kit ships its parts
|
|
3
|
+
beside the type they share. */
|
|
4
|
+
import { Button, Notice, Stack, Text } from '@wordpress/ui';
|
|
5
|
+
/**
|
|
6
|
+
* Renders a screen's title as the page heading.
|
|
7
|
+
* @param props - The title text and the type scale to render it at.
|
|
8
|
+
* @returns The page title element.
|
|
9
|
+
*/
|
|
10
|
+
export function PageTitle({ children, variant = 'heading-xl', }) {
|
|
11
|
+
return (_jsx(Text, { variant: variant, render: _jsx("h1", {}), children: children }));
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Renders a screen: its title top left, an optional subtitle under it,
|
|
15
|
+
* optional actions top right, and the content below.
|
|
16
|
+
* @param props - The title, subtitle, actions, extra class and content.
|
|
17
|
+
* @returns The page element.
|
|
18
|
+
*/
|
|
19
|
+
export function Page({ title, subtitle, actions, className, children }) {
|
|
20
|
+
const classes = className === undefined ? 'godmin-page' : `godmin-page ${className}`;
|
|
21
|
+
return (_jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "row", gap: "md", align: "center", justify: "space-between", children: [_jsxs(Stack, { direction: "column", gap: "xs", children: [_jsx(PageTitle, { children: title }), subtitle !== undefined && (_jsx(Text, { variant: "body-sm", className: "godmin-page__subtitle", children: subtitle }))] }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), children] }));
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Renders a failure message that a screen reader announces.
|
|
25
|
+
* @param props - The message to announce.
|
|
26
|
+
* @returns The error notice element.
|
|
27
|
+
*/
|
|
28
|
+
export function ErrorNotice({ children }) {
|
|
29
|
+
return (_jsx(Notice.Root, { intent: "error", role: "alert", children: _jsx(Notice.Description, { children: children }) }));
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Renders the cursor pagination button for an infinite query, or nothing once
|
|
33
|
+
* every page is loaded.
|
|
34
|
+
* @param props - The query to page through and the button label.
|
|
35
|
+
* @returns The load more button, or null.
|
|
36
|
+
*/
|
|
37
|
+
export function LoadMore({ query, children }) {
|
|
38
|
+
if (!query.hasNextPage) {
|
|
39
|
+
return null;
|
|
40
|
+
}
|
|
41
|
+
return (_jsx(Button, { variant: "minimal", tone: "neutral", size: "compact", onClick: () => void query.fetchNextPage(), disabled: query.isFetchingNextPage, children: children }));
|
|
42
|
+
}
|
package/dist/router.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { CanvasMode } from './frame.js';
|
|
2
|
+
declare module '@tanstack/react-router' {
|
|
3
|
+
interface StaticDataRouteOption {
|
|
4
|
+
canvas?: CanvasMode;
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Returns the canvas the deepest matching route asks for.
|
|
9
|
+
* @returns The canvas mode, padded when no route asks for one.
|
|
10
|
+
*/
|
|
11
|
+
export declare function useCanvas(): CanvasMode;
|
|
12
|
+
/**
|
|
13
|
+
* Returns the current pathname, for a frame to close its drawer on.
|
|
14
|
+
* @returns The pathname of the active location.
|
|
15
|
+
*/
|
|
16
|
+
export declare function useFrameLocation(): string;
|
package/dist/router.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { useRouterState } from '@tanstack/react-router';
|
|
2
|
+
/**
|
|
3
|
+
* Returns the canvas the deepest matching route asks for.
|
|
4
|
+
* @returns The canvas mode, padded when no route asks for one.
|
|
5
|
+
*/
|
|
6
|
+
export function useCanvas() {
|
|
7
|
+
return useRouterState({
|
|
8
|
+
select: (state) => {
|
|
9
|
+
const asking = [...state.matches].reverse().find((match) => match.staticData.canvas);
|
|
10
|
+
return asking?.staticData.canvas ?? 'padded';
|
|
11
|
+
},
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Returns the current pathname, for a frame to close its drawer on.
|
|
16
|
+
* @returns The pathname of the active location.
|
|
17
|
+
*/
|
|
18
|
+
export function useFrameLocation() {
|
|
19
|
+
return useRouterState({ select: (state) => state.location.pathname });
|
|
20
|
+
}
|
package/dist/testing.d.ts
CHANGED
|
@@ -28,6 +28,13 @@ export type LoadModule = () => Promise<Record<string, unknown>>;
|
|
|
28
28
|
* @param load - The loader for the element module, its own import by default.
|
|
29
29
|
*/
|
|
30
30
|
export declare function assertElementPatched(load?: LoadModule): Promise<void>;
|
|
31
|
+
/**
|
|
32
|
+
* Sets what every media query reports, and tells its listeners.
|
|
33
|
+
* @param viewport - Whether queries should report a match.
|
|
34
|
+
*/
|
|
35
|
+
export declare function setViewport(viewport: {
|
|
36
|
+
matches: boolean;
|
|
37
|
+
}): void;
|
|
31
38
|
/**
|
|
32
39
|
* Prepares the test environment a design system application needs.
|
|
33
40
|
*/
|
package/dist/testing.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
2
|
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
-
import { configure, render } from '@testing-library/react';
|
|
3
|
+
import { cleanup, configure, render } from '@testing-library/react';
|
|
4
4
|
import { afterEach } from 'vitest';
|
|
5
5
|
import { AdminRoot } from './admin-root.js';
|
|
6
6
|
/**
|
|
@@ -55,25 +55,78 @@ export async function assertElementPatched(load = () => import('@wordpress/eleme
|
|
|
55
55
|
}
|
|
56
56
|
}
|
|
57
57
|
/**
|
|
58
|
-
*
|
|
58
|
+
* Whether every media query currently reports a match.
|
|
59
59
|
*/
|
|
60
|
-
|
|
60
|
+
let viewportMatches = false;
|
|
61
|
+
/**
|
|
62
|
+
* The listeners registered on the media query lists handed out so far.
|
|
63
|
+
*/
|
|
64
|
+
const viewportListeners = new Set();
|
|
65
|
+
/**
|
|
66
|
+
* Sets what every media query reports, and tells its listeners.
|
|
67
|
+
* @param viewport - Whether queries should report a match.
|
|
68
|
+
*/
|
|
69
|
+
export function setViewport(viewport) {
|
|
70
|
+
viewportMatches = viewport.matches;
|
|
71
|
+
for (const listener of [...viewportListeners]) {
|
|
72
|
+
listener();
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Returns every media query to reporting no match, with no listeners left.
|
|
77
|
+
*/
|
|
78
|
+
function resetViewport() {
|
|
79
|
+
viewportMatches = false;
|
|
80
|
+
viewportListeners.clear();
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Returns a media query list reading the viewport this module controls.
|
|
84
|
+
* @param media - The media query text.
|
|
85
|
+
* @returns The media query list.
|
|
86
|
+
*/
|
|
87
|
+
function mediaQueryList(media) {
|
|
88
|
+
return {
|
|
89
|
+
media,
|
|
90
|
+
get matches() {
|
|
91
|
+
return viewportMatches;
|
|
92
|
+
},
|
|
93
|
+
addEventListener: (_type, listener) => {
|
|
94
|
+
viewportListeners.add(listener);
|
|
95
|
+
},
|
|
96
|
+
removeEventListener: (_type, listener) => {
|
|
97
|
+
viewportListeners.delete(listener);
|
|
98
|
+
},
|
|
99
|
+
addListener: (listener) => {
|
|
100
|
+
viewportListeners.add(listener);
|
|
101
|
+
},
|
|
102
|
+
removeListener: (listener) => {
|
|
103
|
+
viewportListeners.delete(listener);
|
|
104
|
+
},
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Provides the media query API jsdom leaves out.
|
|
109
|
+
*/
|
|
110
|
+
function installMediaQueries() {
|
|
61
111
|
if (typeof window.matchMedia !== 'function') {
|
|
62
|
-
window.matchMedia =
|
|
63
|
-
media,
|
|
64
|
-
matches: false,
|
|
65
|
-
addEventListener: () => { },
|
|
66
|
-
removeEventListener: () => { },
|
|
67
|
-
addListener: () => { },
|
|
68
|
-
removeListener: () => { },
|
|
69
|
-
});
|
|
112
|
+
window.matchMedia = mediaQueryList;
|
|
70
113
|
}
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Provides the feature detection API jsdom leaves out.
|
|
117
|
+
*/
|
|
118
|
+
function installFeatureDetection() {
|
|
71
119
|
if (typeof globalThis.CSS !== 'object' || globalThis.CSS === null) {
|
|
72
120
|
globalThis.CSS = {};
|
|
73
121
|
}
|
|
74
122
|
if (typeof globalThis.CSS.supports !== 'function') {
|
|
75
123
|
globalThis.CSS.supports = () => false;
|
|
76
124
|
}
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Provides the element resize API jsdom leaves out.
|
|
128
|
+
*/
|
|
129
|
+
function installResizeObserver() {
|
|
77
130
|
if (typeof globalThis.ResizeObserver !== 'function') {
|
|
78
131
|
globalThis.ResizeObserver = class {
|
|
79
132
|
observe() { }
|
|
@@ -81,8 +134,18 @@ export function installTestEnvironment() {
|
|
|
81
134
|
disconnect() { }
|
|
82
135
|
};
|
|
83
136
|
}
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Prepares the test environment a design system application needs.
|
|
140
|
+
*/
|
|
141
|
+
export function installTestEnvironment() {
|
|
142
|
+
installMediaQueries();
|
|
143
|
+
installFeatureDetection();
|
|
144
|
+
installResizeObserver();
|
|
84
145
|
configure({ defaultIgnore: WPDS_IGNORE_SELECTOR });
|
|
146
|
+
afterEach(cleanup);
|
|
85
147
|
afterEach(clearAnnouncements);
|
|
148
|
+
afterEach(resetViewport);
|
|
86
149
|
}
|
|
87
150
|
/**
|
|
88
151
|
* Renders the given tree inside the design system host.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { ReactNode } from 'react';
|
|
2
|
+
export interface ToastAction {
|
|
3
|
+
label: string;
|
|
4
|
+
onAct: () => void;
|
|
5
|
+
}
|
|
6
|
+
export interface ToasterHandle {
|
|
7
|
+
show: (message: string, action?: ToastAction) => void;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Returns the handle raising messages in the toast region.
|
|
11
|
+
* @returns The toaster handle.
|
|
12
|
+
*/
|
|
13
|
+
export declare function useToaster(): ToasterHandle;
|
|
14
|
+
export interface ToasterProps {
|
|
15
|
+
children: ReactNode;
|
|
16
|
+
dismissAfter?: number;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Renders the region holding raised messages around the given tree.
|
|
20
|
+
* @param props - The tree the region wraps and how long a toast stays.
|
|
21
|
+
* @returns The wrapped tree with its region.
|
|
22
|
+
*/
|
|
23
|
+
export declare function Toaster({ children, dismissAfter }: ToasterProps): import("react").JSX.Element;
|
package/dist/toaster.js
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
+
/* oxlint-disable react/only-export-components -- the region ships beside the
|
|
3
|
+
hook that reaches it. */
|
|
4
|
+
import { Notice, Stack } from '@wordpress/ui';
|
|
5
|
+
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
|
|
6
|
+
/**
|
|
7
|
+
* How long a toast nobody touches stays on screen.
|
|
8
|
+
*/
|
|
9
|
+
const DISMISS_AFTER = 10000;
|
|
10
|
+
const ToasterContext = createContext(null);
|
|
11
|
+
/**
|
|
12
|
+
* Returns the handle raising messages in the toast region.
|
|
13
|
+
* @returns The toaster handle.
|
|
14
|
+
*/
|
|
15
|
+
export function useToaster() {
|
|
16
|
+
const handle = useContext(ToasterContext);
|
|
17
|
+
if (handle === null) {
|
|
18
|
+
throw new Error('useToaster needs a Toaster above it');
|
|
19
|
+
}
|
|
20
|
+
return handle;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Renders one raised message with its optional action.
|
|
24
|
+
* @param props - The toast and the handler clearing it.
|
|
25
|
+
* @returns The toast element.
|
|
26
|
+
*/
|
|
27
|
+
function Toast({ toast, onClear }) {
|
|
28
|
+
return (_jsxs(Notice.Root, { intent: "neutral", spokenMessage: toast.message, children: [_jsx(Notice.Description, { children: toast.message }), _jsxs(Notice.Actions, { children: [toast.action !== undefined && (_jsx(Notice.ActionButton, { onClick: () => {
|
|
29
|
+
toast.action?.onAct();
|
|
30
|
+
onClear(toast.id);
|
|
31
|
+
}, children: toast.action.label })), _jsx(Notice.ActionButton, { onClick: () => onClear(toast.id), children: "Dismiss" })] })] }));
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Renders the region holding raised messages around the given tree.
|
|
35
|
+
* @param props - The tree the region wraps and how long a toast stays.
|
|
36
|
+
* @returns The wrapped tree with its region.
|
|
37
|
+
*/
|
|
38
|
+
export function Toaster({ children, dismissAfter = DISMISS_AFTER }) {
|
|
39
|
+
const [toasts, setToasts] = useState([]);
|
|
40
|
+
const nextId = useRef(0);
|
|
41
|
+
const timers = useRef(new Set());
|
|
42
|
+
useEffect(() => {
|
|
43
|
+
const held = timers.current;
|
|
44
|
+
return () => {
|
|
45
|
+
for (const timer of held) {
|
|
46
|
+
clearTimeout(timer);
|
|
47
|
+
}
|
|
48
|
+
held.clear();
|
|
49
|
+
};
|
|
50
|
+
}, []);
|
|
51
|
+
const clear = useCallback((id) => {
|
|
52
|
+
setToasts((held) => held.filter((toast) => toast.id !== id));
|
|
53
|
+
}, []);
|
|
54
|
+
const show = useCallback((message, action) => {
|
|
55
|
+
nextId.current += 1;
|
|
56
|
+
const id = nextId.current;
|
|
57
|
+
setToasts((held) => [...held, { id, message, action }]);
|
|
58
|
+
timers.current.add(setTimeout(() => clear(id), dismissAfter));
|
|
59
|
+
}, [clear, dismissAfter]);
|
|
60
|
+
const handle = useMemo(() => ({ show }), [show]);
|
|
61
|
+
return (_jsxs(ToasterContext.Provider, { value: handle, children: [children, _jsx(Stack, { direction: "column", gap: "xs", className: "godmin-toasts", children: toasts.map((toast) => (_jsx(Toast, { toast: toast, onClear: clear }, toast.id))) })] }));
|
|
62
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { useCallback, useSyncExternalStore } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Reports whether the viewport currently matches the given media query.
|
|
4
|
+
* @param query - The media query to evaluate.
|
|
5
|
+
* @returns True while the query matches.
|
|
6
|
+
*/
|
|
7
|
+
export function useMediaQuery(query) {
|
|
8
|
+
const subscribe = useCallback((onChange) => {
|
|
9
|
+
const list = window.matchMedia(query);
|
|
10
|
+
list.addEventListener('change', onChange);
|
|
11
|
+
return () => {
|
|
12
|
+
list.removeEventListener('change', onChange);
|
|
13
|
+
};
|
|
14
|
+
}, [query]);
|
|
15
|
+
return useSyncExternalStore(subscribe, () => window.matchMedia(query).matches);
|
|
16
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gopherium/godmin",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "The admin kit for Gopherium projects: host layer for React admin applications on the WordPress Design System.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -28,6 +28,10 @@
|
|
|
28
28
|
},
|
|
29
29
|
"./base.css": "./dist/base.css",
|
|
30
30
|
"./patches/*": "./patches/*",
|
|
31
|
+
"./router": {
|
|
32
|
+
"types": "./dist/router.d.ts",
|
|
33
|
+
"default": "./dist/router.js"
|
|
34
|
+
},
|
|
31
35
|
"./stylelint": {
|
|
32
36
|
"types": "./dist/stylelint.d.ts",
|
|
33
37
|
"default": "./dist/stylelint.js"
|
|
@@ -54,6 +58,7 @@
|
|
|
54
58
|
"access": "public"
|
|
55
59
|
},
|
|
56
60
|
"peerDependencies": {
|
|
61
|
+
"@tanstack/react-router": "^1.170.0",
|
|
57
62
|
"@testing-library/react": "^16.3.2",
|
|
58
63
|
"@wordpress/style-runtime": ">=0.8.0 <0.9.0",
|
|
59
64
|
"@wordpress/theme": ">=1.1.0 <2.0.0",
|
|
@@ -63,6 +68,9 @@
|
|
|
63
68
|
"vitest": "^4.1.10"
|
|
64
69
|
},
|
|
65
70
|
"peerDependenciesMeta": {
|
|
71
|
+
"@tanstack/react-router": {
|
|
72
|
+
"optional": true
|
|
73
|
+
},
|
|
66
74
|
"@testing-library/react": {
|
|
67
75
|
"optional": true
|
|
68
76
|
},
|
|
@@ -74,6 +82,7 @@
|
|
|
74
82
|
}
|
|
75
83
|
},
|
|
76
84
|
"devDependencies": {
|
|
85
|
+
"@tanstack/react-router": "^1.170.18",
|
|
77
86
|
"@testing-library/react": "^16.3.2",
|
|
78
87
|
"@types/node": "^26.1.2",
|
|
79
88
|
"@types/react": "^19.2.17",
|
|
@@ -86,6 +95,7 @@
|
|
|
86
95
|
"@wordpress/ui": "0.19.0",
|
|
87
96
|
"eslint": "^10.7.0",
|
|
88
97
|
"eslint-plugin-jsdoc": "^63.2.0",
|
|
98
|
+
"eslint-plugin-sonarjs": "^4.2.0",
|
|
89
99
|
"eslint-plugin-tsdoc": "^0.5.2",
|
|
90
100
|
"jsdom": "^29.1.1",
|
|
91
101
|
"oxlint": "^1.71.0",
|