@gopherium/godmin 0.26.0 → 0.28.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,165 @@
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.
80
+ [Toasts](./design-system/toasts.md) in the Design System gives where
81
+ it sits, how it looks, how long it stays and how a reader clears it.
82
+
83
+ `Toaster` renders the region that holds the toasts. Wrap your tree
84
+ once:
85
+
86
+ ```tsx
87
+ <Toaster>
88
+ <YourApp />
89
+ </Toaster>
90
+ ```
91
+
92
+ Then raise messages from any component inside it:
93
+
94
+ ```tsx
95
+ const toaster = useToaster()
96
+
97
+ toaster.show('Post moved to trash.', { label: 'Undo', onAct: restore })
98
+ ```
99
+
100
+ The second argument is optional and adds one action, given as a
101
+ `label` and an `onAct` callback. It shows as a link after the
102
+ message. That covers undo, the main reason to offer an action at
103
+ all. The handle's type is exported as `ToasterHandle`, for holding
104
+ one in a context or a test.
105
+
106
+ Offer the same action somewhere else on the screen too, such as a
107
+ Restore row action in the trash. The toast leaves on its own, and a
108
+ keyboard reader may not reach its action in time. WordPress asks the
109
+ same of its snackbar.
110
+
111
+ `@wordpress/a11y` is a peer dependency, so install it next to
112
+ godmin. `godminDedupe` lists it, which makes `godminSingleCopy` stop
113
+ the build if a second copy slips into your bundle. One copy means
114
+ one live region on the page.
115
+
116
+ `Toaster` takes four props.
117
+ [How long a toast stays](./design-system/toasts.md#how-long-a-toast-stays)
118
+ gives the defaults of the first three, and
119
+ [what a screen reader hears](./design-system/toasts.md#what-a-screen-reader-hears)
120
+ gives the default of the last:
121
+
122
+ - `dismissAfter`, how many milliseconds a toast with no action stays.
123
+ - `actionDismissAfter`, how many milliseconds a toast with an action
124
+ stays.
125
+ - `limit`, how many toasts stay on screen at once.
126
+ - `dismissLabel`, the hint a screen reader reads after the message of
127
+ a toast with no action, to say a click clears it. It is the only
128
+ text godmin puts in a toast, so set it if your application is not
129
+ in English.
130
+
131
+ ### What goes in a toast
132
+
133
+ Use a toast to confirm a change that worked and could otherwise go
134
+ unnoticed: a record saved, a task completed, a file uploaded. Keep
135
+ the message short and in the past tense, like `Post moved to trash.`
136
+
137
+ Name an item in straight double quotes and in full, like
138
+ `"Hello" moved to the trash.` WordPress never cuts a name in its
139
+ snackbar, and godmin does not either.
140
+ [Size](./design-system/toasts.md#size) says how a long one wraps.
141
+
142
+ Use a toast for a write that failed in a dialog or in a run over list
143
+ rows too. WordPress shows those in its snackbar, never inside the
144
+ dialog and never above the list, and godmin's dialogs and list runs
145
+ do the same. Say what failed, in the words your server sent when it
146
+ sent some. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
147
+ shows how to raise one from a dialog.
148
+ [Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
149
+ raises it for you after a run over a list.
150
+
151
+ Keep an [`ErrorNotice`](./screens.md#errornotice) for a failure
152
+ that has to stay on the screen until the user acts:
153
+
154
+ - A screen or a list that failed to load. Show the notice where the
155
+ content would be.
156
+ - A form on a page of its own, not in a dialog. Show the notice next
157
+ to the form, so the user sees what failed while they fix it.
158
+
159
+ Skip the toast in three more cases:
160
+
161
+ - The next screen already says what happened.
162
+ - The user still has to act on the result, like copying a link.
163
+ Keep that on the screen.
164
+ - The change happens right under the pointer and repeats fast, like
165
+ 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.