@gopherium/godmin 0.25.0 → 0.27.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 +9 -15
- package/dist/base.css +3 -2
- package/dist/close-while-open.d.ts +6 -0
- package/dist/close-while-open.js +21 -0
- package/dist/drilldown-item.d.ts +5 -3
- package/dist/drilldown-item.js +6 -6
- package/dist/focus-back.d.ts +25 -0
- package/dist/focus-back.js +125 -0
- package/dist/index.d.ts +9 -1
- package/dist/index.js +5 -1
- package/dist/list-run.d.ts +7 -2
- package/dist/list-run.js +64 -2
- package/dist/list-view.d.ts +1 -7
- package/dist/list-view.js +1 -16
- package/dist/menu-item.d.ts +7 -0
- package/dist/navigation-item.d.ts +8 -0
- package/dist/navigation-item.js +9 -1
- package/dist/navigation-list.js +12 -2
- package/dist/open-on-tap.d.ts +14 -0
- package/dist/open-on-tap.js +17 -0
- package/dist/run-confirm.d.ts +1 -1
- package/dist/run-confirm.js +4 -2
- package/dist/unsaved-text.d.ts +14 -0
- package/dist/unsaved-text.js +25 -0
- package/docs/build-and-versioning.md +190 -0
- package/docs/design-system/accessibility.md +206 -0
- package/docs/design-system/color.md +74 -0
- package/docs/design-system/custom-properties.md +63 -0
- package/docs/design-system/layout.md +157 -0
- package/docs/design-system/motion.md +116 -0
- package/docs/design-system/overview.md +101 -0
- package/docs/design-system/radius-and-elevation.md +129 -0
- package/docs/design-system/typography.md +83 -0
- package/docs/framing-an-application.md +386 -0
- package/docs/lists.md +1511 -0
- package/docs/loading-and-feedback.md +207 -0
- package/docs/overview.md +159 -0
- package/docs/screens.md +419 -0
- package/docs/testing.md +193 -0
- package/package.json +6 -1
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Framing an application
|
|
3
|
+
description: The Frame component gives your app a sidebar and a content canvas, and folds the sidebar into a drawer on small screens.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`Frame` gives your application its layout: a sidebar on the left,
|
|
7
|
+
and a content area beside it, called the canvas. WordPress uses the
|
|
8
|
+
same two names.
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
<Frame.Root location={pathname}>
|
|
12
|
+
<Frame.Sidebar footer={<AccountPanel />} footerNote="Version 1.4.0">
|
|
13
|
+
<YourMenu />
|
|
14
|
+
</Frame.Sidebar>
|
|
15
|
+
<Frame.Canvas canvas={mode}>
|
|
16
|
+
<YourScreen />
|
|
17
|
+
</Frame.Canvas>
|
|
18
|
+
</Frame.Root>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
A region exists because you render its element. There is no
|
|
22
|
+
`showSidebar` flag, so an application without navigation simply does
|
|
23
|
+
not render a `Frame.Sidebar`.
|
|
24
|
+
|
|
25
|
+
Every component's props interface is exported under its own name,
|
|
26
|
+
`FrameRootProps`, `FrameSidebarProps` and `FrameCanvasProps`, for when
|
|
27
|
+
you wrap one in a component of your own.
|
|
28
|
+
|
|
29
|
+
## The sidebar
|
|
30
|
+
|
|
31
|
+
`Frame.Sidebar` holds your menu.
|
|
32
|
+
[The sidebar menu](#the-sidebar-menu) below builds one for you.
|
|
33
|
+
[The frame](./design-system/layout.md#the-frame) gives the sidebar's
|
|
34
|
+
width. Two props fill the bottom of the sidebar:
|
|
35
|
+
|
|
36
|
+
- `footer` sits under the menu and never moves, such as the account
|
|
37
|
+
panel.
|
|
38
|
+
- `footerNote` is one short line of small grey text under the footer,
|
|
39
|
+
such as the version.
|
|
40
|
+
|
|
41
|
+
On a wide screen the sidebar is one region named "Navigation", as in
|
|
42
|
+
the WordPress Site Editor, so a screen reader can jump to it. Pass
|
|
43
|
+
`label` to give it another name. On a small screen the drawer is
|
|
44
|
+
named "Navigation" whatever `label` says.
|
|
45
|
+
|
|
46
|
+
## The sidebar menu
|
|
47
|
+
|
|
48
|
+
With TanStack Router, godmin ships the sidebar menu of the WordPress
|
|
49
|
+
Site Editor. `NavigationScreen` comes from `@gopherium/godmin`, and
|
|
50
|
+
the other parts come from `@gopherium/godmin/router`. Each part has
|
|
51
|
+
the name WordPress's new admin gives it:
|
|
52
|
+
|
|
53
|
+
| Part | What it is |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| `Navigation` | The menu: the root screen, or the sub menu of the page on screen |
|
|
56
|
+
| `NavigationScreen` | One screen of the menu, with its title and Back |
|
|
57
|
+
| `NavigationList` | The list of rows on a screen |
|
|
58
|
+
| `NavigationItem` | A row that goes to a page |
|
|
59
|
+
| `DrilldownItem` | A row that opens a sub menu, with a chevron at its end |
|
|
60
|
+
| `MenuItem` | A row as data |
|
|
61
|
+
|
|
62
|
+
Put `Navigation` in the sidebar and give it your rows as data:
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
import { Link, Outlet } from '@tanstack/react-router'
|
|
66
|
+
import { Frame } from '@gopherium/godmin'
|
|
67
|
+
import { Navigation, useCanvas, useFrameLocation } from '@gopherium/godmin/router'
|
|
68
|
+
import type { MenuItem } from '@gopherium/godmin/router'
|
|
69
|
+
import { can, useSession } from '@gopherium/react-auth'
|
|
70
|
+
import { AccountPanel } from '@gopherium/react-auth/wpds'
|
|
71
|
+
import { comment, page, post } from '@wordpress/icons'
|
|
72
|
+
|
|
73
|
+
const menu: MenuItem[] = [
|
|
74
|
+
{ label: 'Posts', to: '/posts', icon: post },
|
|
75
|
+
{ label: 'Pages', to: '/pages', icon: page },
|
|
76
|
+
{ label: 'Chats', to: '/chats', icon: comment },
|
|
77
|
+
]
|
|
78
|
+
|
|
79
|
+
function Layout() {
|
|
80
|
+
const user = useSession().data
|
|
81
|
+
return (
|
|
82
|
+
<Frame.Root location={useFrameLocation()}>
|
|
83
|
+
<Frame.Sidebar footer={<AccountPanel />}>
|
|
84
|
+
<Navigation
|
|
85
|
+
title="MyApp"
|
|
86
|
+
items={menu}
|
|
87
|
+
home={<Link to="/posts" />}
|
|
88
|
+
can={(capability) => can(user, capability)}
|
|
89
|
+
/>
|
|
90
|
+
</Frame.Sidebar>
|
|
91
|
+
<Frame.Canvas canvas={useCanvas()}>
|
|
92
|
+
<Outlet />
|
|
93
|
+
</Frame.Canvas>
|
|
94
|
+
</Frame.Root>
|
|
95
|
+
)
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
- `title` is the title of the root screen, such as your app's name.
|
|
100
|
+
- `items` are the rows of the root screen.
|
|
101
|
+
- `home` is a link to the page your home address lands on. Back on a
|
|
102
|
+
sub menu goes there.
|
|
103
|
+
- `can` tells whether the reader holds a capability. See
|
|
104
|
+
[hiding rows](#hiding-rows-a-reader-cannot-open).
|
|
105
|
+
|
|
106
|
+
Each row is a link with its icon, a glyph from `@wordpress/icons`,
|
|
107
|
+
then its label. A row with no icon keeps a blank in its place when
|
|
108
|
+
other rows have one, so the labels line up. The row of the page on
|
|
109
|
+
screen is highlighted, and it stays highlighted on every address
|
|
110
|
+
under it, so Posts stays highlighted on `/posts/new`.
|
|
111
|
+
|
|
112
|
+
`Navigation` needs a `Frame.Root` above it, which holds what the
|
|
113
|
+
sidebar parts share.
|
|
114
|
+
|
|
115
|
+
### Sub menus
|
|
116
|
+
|
|
117
|
+
A route opens a sub menu by naming a screen in `staticData.Sidebar`.
|
|
118
|
+
Every page under that route shows the screen in the sidebar:
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
import { createRoute } from '@tanstack/react-router'
|
|
122
|
+
import { NavigationScreen } from '@gopherium/godmin'
|
|
123
|
+
import { NavigationItem, NavigationList } from '@gopherium/godmin/router'
|
|
124
|
+
|
|
125
|
+
const chatsRoute = createRoute({
|
|
126
|
+
getParentRoute: () => rootRoute,
|
|
127
|
+
path: '/chats',
|
|
128
|
+
staticData: { Sidebar: ChatsMenu },
|
|
129
|
+
})
|
|
130
|
+
|
|
131
|
+
function ChatsMenu() {
|
|
132
|
+
const chats = useChats()
|
|
133
|
+
return (
|
|
134
|
+
<NavigationScreen title="Chats">
|
|
135
|
+
<NavigationList>
|
|
136
|
+
{chats.map((chat) => (
|
|
137
|
+
<NavigationItem key={chat.id} to="/chats/$chatId" params={{ chatId: chat.id }}>
|
|
138
|
+
{chat.title}
|
|
139
|
+
</NavigationItem>
|
|
140
|
+
))}
|
|
141
|
+
</NavigationList>
|
|
142
|
+
</NavigationScreen>
|
|
143
|
+
)
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Nothing else is needed. The Chats row of `menu` opens that route, so
|
|
148
|
+
it draws as a `DrilldownItem`, with a chevron. A click on it slides
|
|
149
|
+
the sub menu in and moves the focus to Back. Back goes to `home`,
|
|
150
|
+
slides the root screen in and puts the focus back on the Chats row.
|
|
151
|
+
In a right-to-left language the chevrons and the slide turn around.
|
|
152
|
+
The slide does not play when the system asks for reduced motion.
|
|
153
|
+
|
|
154
|
+
`NavigationList` draws the rows of `items` first, then the rows you
|
|
155
|
+
draw yourself as its children. Draw a row yourself with
|
|
156
|
+
`NavigationItem`, or with `DrilldownItem` when it opens a sub menu.
|
|
157
|
+
Both take `icon` and the props of a TanStack `Link`, such as `to`,
|
|
158
|
+
`params`, `className` and `onClick`. They draw their own list item,
|
|
159
|
+
so put them inside a `NavigationList`. The screens page describes
|
|
160
|
+
[`NavigationScreen`](./screens.md#navigationscreen).
|
|
161
|
+
|
|
162
|
+
### Hiding rows a reader cannot open
|
|
163
|
+
|
|
164
|
+
A route names the capability a reader needs in
|
|
165
|
+
`staticData.capability`. A `MenuItem` can name one of its own in
|
|
166
|
+
`capability`. A row shows only when `can` allows its own capability
|
|
167
|
+
and the capability of every route its address opens. Without `can`,
|
|
168
|
+
every row that needs a capability is hidden.
|
|
169
|
+
|
|
170
|
+
`fallback` is a row to show in its place. It shows when the reader
|
|
171
|
+
may open it:
|
|
172
|
+
|
|
173
|
+
```tsx
|
|
174
|
+
const usersRow: MenuItem = {
|
|
175
|
+
label: 'Users',
|
|
176
|
+
to: '/users',
|
|
177
|
+
capability: 'users.manage',
|
|
178
|
+
fallback: { label: 'API tokens', to: '/tokens' },
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Code outside the sidebar can ask the same question with
|
|
183
|
+
`useCanAccess`:
|
|
184
|
+
|
|
185
|
+
```tsx
|
|
186
|
+
const canAccess = useCanAccess((capability) => can(user, capability))
|
|
187
|
+
const showUsers = canAccess({ to: '/users' })
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### A count beside a row
|
|
191
|
+
|
|
192
|
+
`MenuCount` draws the small number WordPress shows beside a menu
|
|
193
|
+
label, such as how many updates wait. Pass it as a row's `suffix`:
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
<NavigationList>
|
|
197
|
+
<NavigationItem to="/updates" suffix={<MenuCount count={3} label="3 updates available" />}>
|
|
198
|
+
Updates
|
|
199
|
+
</NavigationItem>
|
|
200
|
+
</NavigationList>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
- It draws nothing when `count` is zero.
|
|
204
|
+
- The number follows the reader's number format, so 1234 reads as
|
|
205
|
+
1,234 in English.
|
|
206
|
+
- A screen reader reads `label` in place of the number, so pass a
|
|
207
|
+
whole sentence in the reader's language.
|
|
208
|
+
|
|
209
|
+
A `DrilldownItem` takes a `suffix` too, drawn before its chevron.
|
|
210
|
+
When `Navigation` draws your rows from data, give the `MenuItem` a
|
|
211
|
+
`count` instead and it draws the `MenuCount` for you:
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
const updates: MenuItem = {
|
|
215
|
+
label: 'Updates',
|
|
216
|
+
to: '/updates',
|
|
217
|
+
count: { value: 3, label: '3 updates available' },
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## The canvas on a wide screen
|
|
222
|
+
|
|
223
|
+
On a wide screen the canvas is a panel with a margin around it, the
|
|
224
|
+
way the WordPress Site Editor frames its canvas.
|
|
225
|
+
[The canvas](./design-system/layout.md#the-canvas) gives the size of
|
|
226
|
+
that margin and when the canvas leaves it out.
|
|
227
|
+
|
|
228
|
+
## What happens on a small screen
|
|
229
|
+
|
|
230
|
+
As the screen gets narrower, the frame changes three times, at the
|
|
231
|
+
widths [Breakpoints](./design-system/layout.md#breakpoints) lists:
|
|
232
|
+
|
|
233
|
+
- The sidebar goes away. In its place you get a top bar, like the
|
|
234
|
+
WordPress admin bar on a phone. Its menu button opens the same
|
|
235
|
+
sidebar, menu and footer, in a drawer.
|
|
236
|
+
- The canvas stretches to the screen edges, with no margin, no
|
|
237
|
+
rounded corners and no shadow, the way a WordPress admin page meets
|
|
238
|
+
a small screen.
|
|
239
|
+
- The canvas also uses tighter padding.
|
|
240
|
+
|
|
241
|
+
[The frame](./design-system/layout.md#the-frame) gives the sizes of
|
|
242
|
+
the top bar and the drawer, and
|
|
243
|
+
[the canvas](./design-system/layout.md#the-canvas) gives its padding.
|
|
244
|
+
|
|
245
|
+
The drawer looks like the phone sidebar of WordPress's new admin and
|
|
246
|
+
dims the page under it. It closes when the reader opens another page.
|
|
247
|
+
It stays open when a sub menu opens or Back closes one, so the reader
|
|
248
|
+
can pick a row in it.
|
|
249
|
+
|
|
250
|
+
Two `Frame.Sidebar` props exist for the top bar:
|
|
251
|
+
|
|
252
|
+
- `brand` is a small element such as a home link, shown beside the
|
|
253
|
+
menu button. The top bar only exists on a small screen, so
|
|
254
|
+
`brand` is not rendered at all on a wide one. Do not make it a
|
|
255
|
+
heading. [Heading levels](./screens.md#heading-levels) says
|
|
256
|
+
which part draws each one.
|
|
257
|
+
- `menuLabel` is the name of the menu button. It defaults to "Open
|
|
258
|
+
navigation panel", WordPress's words.
|
|
259
|
+
|
|
260
|
+
The widths are exported, so your own rules can change at the same
|
|
261
|
+
points as the frame and as WordPress.
|
|
262
|
+
[Breakpoints](./design-system/layout.md#breakpoints) lists each one
|
|
263
|
+
and what changes below it. `useMediaQuery` answers any media query
|
|
264
|
+
and re-renders your component when the answer changes:
|
|
265
|
+
|
|
266
|
+
```tsx
|
|
267
|
+
const small = useMediaQuery(SMALL_VIEWPORT)
|
|
268
|
+
const sheet = useMediaQuery(`(max-width: ${SHEET_BREAKPOINT - 1}px)`)
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
## godmin's own words
|
|
272
|
+
|
|
273
|
+
The frame and the sidebar draw a few words of their own: "Back",
|
|
274
|
+
"Navigation", "Open navigation panel" and "Close navigation panel".
|
|
275
|
+
The last one names a close button at the end of the drawer, which
|
|
276
|
+
only a screen reader meets. godmin translates them in the WordPress
|
|
277
|
+
`default` text domain, as the design system does. The Spanish and
|
|
278
|
+
French catalogues that `listChromeCatalogFor` returns hold them, so
|
|
279
|
+
load it as [the list chrome](./lists.md#the-list-chrome-in-spanish)
|
|
280
|
+
shows.
|
|
281
|
+
|
|
282
|
+
## Coloring the regions
|
|
283
|
+
|
|
284
|
+
`chromeColor` sets the theme color of the frame, and `canvasColor`
|
|
285
|
+
the one of the canvas. Each accepts the same color values as the
|
|
286
|
+
design system theme provider. Pass neither and the frame takes
|
|
287
|
+
godmin's defaults.
|
|
288
|
+
[The three seeds](./design-system/color.md#the-three-seeds) gives
|
|
289
|
+
them, and
|
|
290
|
+
[which token paints each part](./design-system/color.md#which-token-paints-each-part)
|
|
291
|
+
gives the token each region paints with.
|
|
292
|
+
|
|
293
|
+
The theme provider works out every grey from the background you
|
|
294
|
+
give it. With the default chrome color, the sidebar and the top bar
|
|
295
|
+
come out `#1d2428`, one step from the WordPress admin bar, `#1d2327`.
|
|
296
|
+
|
|
297
|
+
With the default canvas color, the canvas comes out white, like a
|
|
298
|
+
WordPress page, with the exact WordPress greys, row lines `#f0f0f0`
|
|
299
|
+
and muted text `#707070`. A white canvas `background` moves every
|
|
300
|
+
grey a step lighter.
|
|
301
|
+
|
|
302
|
+
Dialogs, drawers, menus, popovers and selects you open inside the
|
|
303
|
+
frame do not take these colors. They use the `AdminRoot` color
|
|
304
|
+
instead. Tooltips still follow the frame colors. The navigation
|
|
305
|
+
drawer is an exception and keeps `chromeColor`.
|
|
306
|
+
|
|
307
|
+
## Two canvas modes
|
|
308
|
+
|
|
309
|
+
`Frame.Canvas` takes `canvas`, typed as `CanvasMode`, with two
|
|
310
|
+
values:
|
|
311
|
+
|
|
312
|
+
- `padded`, the default, gives your screen comfortable padding.
|
|
313
|
+
- `bleed` removes it, for a screen that manages its own edges, such
|
|
314
|
+
as a full-height table or a two-pane chat view.
|
|
315
|
+
|
|
316
|
+
## Notices for the whole application
|
|
317
|
+
|
|
318
|
+
`Frame.Canvas` takes `notices`, for messages that belong to the whole
|
|
319
|
+
application rather than to one screen, such as "a new version is
|
|
320
|
+
available". They are drawn in a band above your screen:
|
|
321
|
+
|
|
322
|
+
```tsx
|
|
323
|
+
<Frame.Canvas canvas={mode} notices={updateWaits && <UpdateNotice />}>
|
|
324
|
+
<YourScreen />
|
|
325
|
+
</Frame.Canvas>
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
- On a `padded` canvas the notices sit 12px apart and line up with
|
|
329
|
+
the page title at every width.
|
|
330
|
+
- On a `bleed` canvas they run edge to edge as square strips, the way
|
|
331
|
+
the WordPress editors draw theirs.
|
|
332
|
+
- When `notices` renders nothing, there is no band at all.
|
|
333
|
+
|
|
334
|
+
Draw each notice with the design system's `Notice`. The band only
|
|
335
|
+
places them. A screen reader hears a new notice only when you
|
|
336
|
+
announce it, as the `Notice` documentation explains.
|
|
337
|
+
|
|
338
|
+
## Routes and the frame
|
|
339
|
+
|
|
340
|
+
`Frame.Root` takes `location` as a plain string. When the string
|
|
341
|
+
changes, it closes the drawer, unless a sub menu move made the
|
|
342
|
+
change. That is enough: click any link, the address changes, the
|
|
343
|
+
drawer closes. It works for links a plugin added too, because nothing
|
|
344
|
+
has to be registered. This is also why the main entry point imports
|
|
345
|
+
no router.
|
|
346
|
+
|
|
347
|
+
With TanStack Router, `@gopherium/godmin/router` gives you the string
|
|
348
|
+
and lets each route declare the canvas it wants:
|
|
349
|
+
|
|
350
|
+
```tsx
|
|
351
|
+
createRoute({ getParentRoute: () => rootRoute, path: 'threads/$id', staticData: { canvas: 'bleed' } })
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Read the declarations back with two hooks:
|
|
355
|
+
|
|
356
|
+
```tsx
|
|
357
|
+
const mode = useCanvas() // hand this to Frame.Canvas
|
|
358
|
+
const pathname = useFrameLocation() // hand this to Frame.Root
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
When routes nest, the deepest match that declares a canvas wins,
|
|
362
|
+
and a route that declares nothing inherits from the routes above
|
|
363
|
+
it. So a section can declare `bleed` once and every screen inside
|
|
364
|
+
it gets it, and one child can still declare `padded` to opt back
|
|
365
|
+
out. Only when no matched route declares anything does `useCanvas`
|
|
366
|
+
fall back to `padded`.
|
|
367
|
+
|
|
368
|
+
`useFrameLocation` answers the path followed by the search, so the
|
|
369
|
+
drawer also closes when only the search changes.
|
|
370
|
+
|
|
371
|
+
`routerDefaults()` returns the options WordPress's new admin gives
|
|
372
|
+
the same router. Spread them into `createRouter`:
|
|
373
|
+
|
|
374
|
+
```tsx
|
|
375
|
+
const router = createRouter({ routeTree, ...routerDefaults() })
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
A page then starts to load when the pointer rests on its link or the
|
|
379
|
+
keyboard reaches it.
|
|
380
|
+
[Moving between pages](./loading-and-feedback.md#moving-between-pages)
|
|
381
|
+
says what the reader sees while it loads.
|
|
382
|
+
|
|
383
|
+
`@tanstack/react-router` is an optional peer dependency, any 1.x
|
|
384
|
+
release from 1.170.44, needed only for this entry point. The main entry point
|
|
385
|
+
never imports it, so an application on another router just passes
|
|
386
|
+
`location` itself.
|