@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,207 @@
1
+ ---
2
+ title: Loading and feedback
3
+ description: Ghost placeholders while data loads, a fade for the content that replaces them, and toasts for messages.
4
+ ---
5
+
6
+ While a screen waits for its data, show a ghost: grey shapes where
7
+ the content is about to appear. When the data arrives, fade the
8
+ real content in. godmin ships both halves, plus the toast region
9
+ for short messages.
10
+
11
+ ## The ghosts
12
+
13
+ `LoadingScreen` stands in for a whole screen. `LoadingRows` stands
14
+ in for a list inside a screen whose surroundings are already
15
+ visible:
16
+
17
+ ```tsx
18
+ if (reports.isPending) {
19
+ return <LoadingRows label="Loading reports." rows={8} />
20
+ }
21
+ return <ReportTable className="godmin-arrival" />
22
+ ```
23
+
24
+ `label` is required on both. Write the sentence you would have
25
+ shown as text, like `Loading reports.` Sighted users see the
26
+ shapes, and screen reader users hear the label, announced from a
27
+ visually hidden status region. The shapes themselves are hidden
28
+ from assistive technology.
29
+
30
+ `LoadingRows` takes `rows`, which defaults to 5. `LoadingScreen`
31
+ draws a title bar and three text lines, with no count to set.
32
+
33
+ ## Why a ghost does not appear immediately
34
+
35
+ A ghost stays invisible for its first 150ms. If the data arrives
36
+ faster, which it usually does, the user never sees it. Without that
37
+ delay every fast load would flash grey for a moment, and the flash
38
+ reads as something being wrong.
39
+
40
+ The delay lives in the stylesheet, so there is nothing to manage in
41
+ your code. Render the ghost from the pending flag and you are done.
42
+ No timers, no extra state.
43
+
44
+ If you are coming from 0.4.0: the `useLoadingGate` hook is gone as
45
+ of 0.5.0. It held ghosts on screen for a minimum time after the
46
+ data arrived, which made fast screens feel slow. Render from the
47
+ pending flag and let the stylesheet do the rest.
48
+
49
+ ## Fading the content in
50
+
51
+ Give the content that replaces a ghost the `godmin-arrival` class
52
+ and it fades in instead of snapping in:
53
+
54
+ ```tsx
55
+ return <ReportTable className="godmin-arrival" />
56
+ ```
57
+
58
+ The fade is a short opacity ramp with no delay, so the content
59
+ starts appearing the moment it is ready. Together with the ghost's
60
+ own fade, the swap reads as one motion.
61
+
62
+ ## Moving between pages
63
+
64
+ A router can draw a loading screen while the next page loads.
65
+ WordPress's new admin draws none. To do the same, spread
66
+ [`routerDefaults()`](./framing-an-application.md#routes-and-the-frame)
67
+ into your router, and give it no `defaultPendingComponent` and no
68
+ route a `pendingComponent`. Then:
69
+
70
+ - The page on screen stays until the next one has its code and data.
71
+ - A page starts to load when the pointer rests on its link or the
72
+ keyboard reaches it, so the wait is often over before the click.
73
+ - A page that fetches its own data after it opens draws its ghost, as
74
+ above.
75
+
76
+ ## Toasts
77
+
78
+ A toast is a short message that says how something went, then
79
+ removes itself. godmin draws it like the WordPress snackbar: a dark,
80
+ slightly see-through box with white 13px text, 32px above the bottom
81
+ edge. It sits at the center of the canvas, so beside the sidebar it
82
+ lines up with your content, and it sits at the center of the window
83
+ when no sidebar is on screen.
84
+
85
+ The numbers are the snackbar's own:
86
+
87
+ - 12px of padding above and below the text and 20px on each side.
88
+ A one line toast is 42px tall, with or without an action.
89
+ - 4px rounded corners and the small WordPress shadow under it.
90
+ - As wide as its message, up to 560px. On a screen narrower than
91
+ 600px it spans the width, with a 16px gap on each side, and still
92
+ stops at 560px.
93
+ - 8px between two toasts on screen at once.
94
+ - On a toast with an action, the action sits at least 32px after the
95
+ message and the close button at least 24px after the action. On a
96
+ phone, where the toast spans the width, the snackbar spreads the
97
+ spare room between the three, and godmin does the same.
98
+ - The close button is the snackbar's own cross, the ✕ character in
99
+ the toast's text. When a message wraps, the action and the cross
100
+ stay on its first line.
101
+ - The action is a white underlined link that loses its underline
102
+ under the pointer. Keyboard focus draws a dotted white line around
103
+ it, and a white inner line with a blue ring around a plain toast,
104
+ as the snackbar does.
105
+
106
+ On a list page the toast floats over the list footer, as it does in
107
+ WordPress.
108
+
109
+ An open dialog covers the toasts, as WordPress covers its snackbar.
110
+ On a wide screen a toast shows dimmed under the dark layer around the
111
+ dialog, and on a phone it sits behind the sheet. Screen readers still
112
+ hear it, because every message is also spoken. Most dialogs close as
113
+ their write starts or ends, so their toast shows in full. A
114
+ [form dialog](./lists.md#a-form-dialog) stays open after a
115
+ failure, so its toast shows under it, as in WordPress.
116
+
117
+ `Toaster` renders the region that holds the toasts. Wrap your tree
118
+ once:
119
+
120
+ ```tsx
121
+ <Toaster>
122
+ <YourApp />
123
+ </Toaster>
124
+ ```
125
+
126
+ Then raise messages from any component inside it:
127
+
128
+ ```tsx
129
+ const toaster = useToaster()
130
+
131
+ toaster.show('Post moved to trash.', { label: 'Undo', onAct: restore })
132
+ ```
133
+
134
+ The second argument is optional and adds one action, given as a
135
+ `label` and an `onAct` callback. It shows as a white link after the
136
+ message. That covers undo, the main reason to offer an action at
137
+ all. The handle's type is exported as `ToasterHandle`, for holding
138
+ one in a context or a test.
139
+
140
+ ### How a toast behaves
141
+
142
+ - It stays 6 seconds, then fades out. Every toast keeps its own
143
+ timer, so a toast a screen raises as it mounts leaves on time even
144
+ under React strict mode, which mounts the screen twice in
145
+ development.
146
+ - At most three are on screen at once. The newest sits at the
147
+ bottom, and when a fourth arrives the oldest leaves.
148
+ - A toast with no action goes away when you click anywhere on it.
149
+ A toast with an action shows a small close button instead, so
150
+ there is never a button inside another button.
151
+ - Screen readers hear each message once, politely, through `speak`
152
+ from `@wordpress/a11y`. The toast region itself is not a live
153
+ region, so nothing is read twice.
154
+ - When a toast that holds keyboard focus goes away, focus moves to
155
+ the toast region instead of falling back to the top of the page.
156
+ The next Tab carries on from there.
157
+ - The fades stop when the system asks for reduced motion.
158
+
159
+ `@wordpress/a11y` is a peer dependency, so install it next to
160
+ godmin. `godminDedupe` lists it, which makes `godminSingleCopy` stop
161
+ the build if a second copy slips into your bundle. One copy means
162
+ one live region on the page.
163
+
164
+ `Toaster` takes four props:
165
+
166
+ - `dismissAfter`, how many milliseconds a toast stays. The default
167
+ is 6000.
168
+ - `limit`, how many toasts stay on screen at once. The default is 3.
169
+ - `nameLength`, how many characters of a name a toast shows before
170
+ an ellipsis. The default is 45. See
171
+ [naming an item in a toast](./lists.md#naming-an-item-in-a-toast).
172
+ - `dismissLabel`, the name of the close button. On a toast with no
173
+ action it is the hint a screen reader reads after the message. No
174
+ tooltip shows when the pointer rests on the toast, as in WordPress.
175
+ It defaults to `Dismiss`, and it is the only text godmin puts in a
176
+ toast, so set it if your application is not in English.
177
+
178
+ ### What goes in a toast
179
+
180
+ Use a toast to confirm a change that worked and could otherwise go
181
+ unnoticed: a record saved, a task completed, a file uploaded. Keep
182
+ the message short and in the past tense, like `Post moved to trash.`
183
+
184
+ Use a toast for a write that failed in a dialog or in a run over list
185
+ rows too. WordPress shows those in its snackbar, never inside the
186
+ dialog and never above the list, and godmin's dialogs and list runs
187
+ do the same. Say what failed, in the words your server sent when it
188
+ sent some. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
189
+ shows how to raise one from a dialog.
190
+ [Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
191
+ raises it for you after a run over a list.
192
+
193
+ Keep an [`ErrorNotice`](./screens.md#errornotice) for a failure
194
+ that has to stay on the screen until the user acts:
195
+
196
+ - A screen or a list that failed to load. Show the notice where the
197
+ content would be.
198
+ - A form on a page of its own, not in a dialog. Show the notice next
199
+ to the form, so the user sees what failed while they fix it.
200
+
201
+ Skip the toast in three more cases:
202
+
203
+ - The next screen already says what happened.
204
+ - The user still has to act on the result, like copying a link.
205
+ Keep that on the screen.
206
+ - The change happens right under the pointer and repeats fast, like
207
+ moving a row up. A toast for every press piles up.
@@ -0,0 +1,159 @@
1
+ ---
2
+ title: Overview
3
+ description: What godmin is, what it ships, and the two lines of setup that get an admin app running.
4
+ ---
5
+
6
+ `@gopherium/godmin` is the base layer for a React admin application
7
+ built on the WordPress Design System (WPDS). It takes care of the
8
+ groundwork such an application needs before its first screen can
9
+ render: loading the design tokens, ordering the CSS, keeping
10
+ overlays on top, and preparing your bundler and your test runner.
11
+
12
+ Why does that layer exist at all? The design system already ships
13
+ most of what an admin application is made of:
14
+
15
+ | Layer | What it is | Package |
16
+ | --- | --- | --- |
17
+ | Design tokens | Named values for colors, spacing and type | `@wordpress/theme` |
18
+ | Primitives | Buttons, menus, dialogs, text | `@wordpress/ui` |
19
+ | Data screens | Ready made list and table views | `@wordpress/dataviews` |
20
+ | Page chrome | The bars and panels around a page | `@wordpress/admin-ui` |
21
+
22
+ Inside WordPress, the glue underneath those packages comes from
23
+ WordPress itself, through PHP and `@wordpress/boot`. An application
24
+ that is not WordPress gets nothing, and ends up hand-writing that
25
+ glue. godmin is the glue as a package, and nothing more. It never
26
+ duplicates something the packages above already ship.
27
+
28
+ ## The entry points
29
+
30
+ | Entry point | Contents |
31
+ | --- | --- |
32
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
33
+ | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
34
+ | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
35
+ | `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |
36
+ | `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `routerDefaults`, the `canvas`, `Sidebar` and `capability` route static data |
37
+ | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
38
+ | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
39
+ | `@gopherium/godmin/stylelint` | The design system stylelint rules |
40
+
41
+ All the design system packages are peer dependencies. A peer
42
+ dependency is a package your application installs and pins itself.
43
+ You stay in control of the exact design system versions you run,
44
+ and godmin never redistributes them. From 0.13.0 that includes
45
+ `@wordpress/icons`, which draws the arrows and the trash of
46
+ `RowControls`. From 0.25.0 it also includes `@wordpress/i18n`, which
47
+ translates the few words godmin draws itself, such as Back in the
48
+ sidebar.
49
+
50
+ ## Setup
51
+
52
+ Install:
53
+
54
+ ```sh
55
+ pnpm add @gopherium/godmin
56
+ ```
57
+
58
+ Then import the stylesheet once at your entry point and mount
59
+ `AdminRoot` around your tree:
60
+
61
+ ```tsx
62
+ import '@gopherium/godmin/base.css'
63
+ import { AdminRoot } from '@gopherium/godmin'
64
+
65
+ createRoot(document.getElementById('app')!).render(
66
+ <AdminRoot>
67
+ <YourApp />
68
+ </AdminRoot>,
69
+ )
70
+ ```
71
+
72
+ That is the whole setup. Here is what those two lines do for you:
73
+
74
+ - Load the design tokens. You do not import
75
+ `@wordpress/theme/design-tokens.css` yourself.
76
+ - Declare the CSS cascade layers in the order `wp-ui, godmin`. A
77
+ cascade layer decides which stylesheet wins when two rules
78
+ disagree, and this order lets godmin's rules build on the design
79
+ system's.
80
+ - Isolate a stacking context. In plain words: popovers and dialogs
81
+ will draw above your page instead of behind it.
82
+ - Enable the overlay slot that lets design system overlays stack
83
+ above `@wordpress/components` ones.
84
+ - Give the page the design system's own blue as its accent, the
85
+ color of primary buttons, selected rows and focus rings. Pass
86
+ your own `color` to use another one.
87
+
88
+ `AdminRoot` also accepts the `color`, `cursor` and `cornerRadius`
89
+ theme settings, which it hands to the design system theme provider,
90
+ and `as` for when the host element should be something other than a
91
+ `div`.
92
+
93
+ ## Changing the page appearance
94
+
95
+ `base.css` sets the page font, color and background from design
96
+ tokens. It does so inside the `godmin` CSS layer, and a rule inside
97
+ a layer loses to any plain rule outside one. So to change how the
98
+ page looks, write an ordinary rule in your own stylesheet and it
99
+ wins. No `!important`, no specificity tricks. Colors are the one
100
+ exception. Change them through the seed props that
101
+ [Color](./design-system/color.md#the-three-seeds) lists, not with a
102
+ rule of your own.
103
+
104
+ Two notes:
105
+
106
+ - A few rules sit outside the layer on purpose.
107
+ `body { position: relative }` is one: overlays position themselves
108
+ against it, so overriding it breaks their backdrops. The others set
109
+ DataViews inside a page, such as the list toolbar, the footer and
110
+ the avatar box. The DataViews stylesheet sits in no layer, so a
111
+ rule inside one would lose to it. Leave them in place.
112
+ - The documented class names on the [screens
113
+ page](./screens.md#stylesheet-helpers) and the public
114
+ [custom properties](./design-system/custom-properties.md#public-custom-properties)
115
+ are the stable names to style with. The stylesheet's other class
116
+ names, such as those of the frame, and its other custom properties
117
+ are not, and can change in any release.
118
+
119
+ If you declare CSS layers of your own, include godmin's in your
120
+ order:
121
+
122
+ ```css
123
+ @layer wp-ui, godmin, my-app;
124
+ ```
125
+
126
+ ## Styling an iframe or a popup
127
+
128
+ The design system injects its styles into the current document
129
+ only, so an iframe or a popup window starts out unstyled.
130
+ `useTokenDocument` registers the extra document and keeps it
131
+ supplied with styles, which is what an embedded editor canvas
132
+ needs:
133
+
134
+ ```tsx
135
+ const [canvas, setCanvas] = useState<Document | null>(null)
136
+ useTokenDocument(canvas)
137
+
138
+ return <iframe src="/canvas" onLoad={(event) => setCanvas(event.currentTarget.contentDocument)} />
139
+ ```
140
+
141
+ Keep the document in state, not in a ref. React fills a ref after it
142
+ renders and does not render again for it. So a ref read during render
143
+ hands the hook nothing. The load handler stores the document once the
144
+ iframe has one, and again each time the iframe loads a new page. The
145
+ hook accepts `null`, so the state can start empty.
146
+
147
+ ## Where it sits
148
+
149
+ godmin is a TypeScript brick, unlike its Go siblings
150
+ [authkit](https://docs.gopherium.org/authentication/overview/) and
151
+ [pluginkit](https://docs.gopherium.org/plugins/overview/). It pairs with
152
+ [`@gopherium/react-auth`](https://docs.gopherium.org/authentication/react-integration/),
153
+ whose login and user screens are built from the same design system.
154
+
155
+ Read [framing an application](./framing-an-application.md)
156
+ next for the layout and the sidebar menu. And read
157
+ [build configuration](./build-and-versioning.md) before your
158
+ first build, because a duplicate package is much easier to avoid
159
+ than to debug.