@gopherium/godmin 0.26.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.
@@ -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.