@gopherium/godmin 0.6.0 → 0.7.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 CHANGED
@@ -2,43 +2,17 @@
2
2
 
3
3
  Gopherium's admin kit
4
4
 
5
- GodMin is the host layer for a React admin application built on the WordPress
6
- Design System. Five layers make up such an application, and four already have
7
- owners upstream: `@wordpress/theme` owns tokens, `@wordpress/ui` owns
8
- primitives, `@wordpress/dataviews` owns data screens, and `@wordpress/admin-ui`
9
- owns page chrome. The fifth is the host layer, which WordPress supplies to
10
- itself through PHP and `@wordpress/boot`, and which nothing supplies to an
11
- application that is not WordPress. GodMin is that layer.
5
+ GodMin is the base layer for a React admin application built on the WordPress
6
+ Design System. It handles the groundwork such an application needs before its
7
+ first screen renders: loading the design tokens, ordering the CSS, keeping
8
+ overlays on top, and preparing your bundler and your test runner.
12
9
 
13
- Every export earns its place against one of three tests: it closes a documented
14
- upstream gap, it satisfies a documented host requirement, or it owns a contract
15
- that two published packages each expect the application to hand-write. Nothing
16
- here duplicates something upstream ships.
10
+ The design system already ships the tokens, the primitives, the data screens
11
+ and the page chrome. Inside WordPress, the glue underneath them comes from
12
+ WordPress itself. An application that is not WordPress gets nothing, and ends
13
+ up hand-writing that glue. GodMin is the glue as a package, and nothing more.
17
14
 
18
- ## What is in it
19
-
20
- | Entry point | Contents |
21
- | --- | --- |
22
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `NavScreen`, `ErrorNotice`, `LoadMore`, `LoadingScreen`, `LoadingRows`, `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` |
26
- | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy` |
27
- | `@gopherium/godmin/stylelint` | the design system stylelint rules |
28
- | `@gopherium/godmin/patches` | the React 19 patch for `@wordpress/element`, temporary |
29
-
30
- ## Status
31
-
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.
15
+ **[Documentation](https://docs.gopherium.org/admin-ui/overview/)**
42
16
 
43
17
  ## Install
44
18
 
@@ -46,14 +20,13 @@ upstream fix. See the CHANGELOG for what each release adds.
46
20
  pnpm add @gopherium/godmin
47
21
  ```
48
22
 
49
- GodMin declares the design system as peer dependencies, so your application
50
- resolves and pins them. The window this build was tested against is exported as
51
- `SUPPORTED_WPDS` and enforced by the declared peer ranges.
23
+ The design system packages are peer dependencies, so your application resolves
24
+ and pins them. GodMin never redistributes them.
52
25
 
53
26
  ## Setup
54
27
 
55
- Import the stylesheet once, at your application entry point, then mount
56
- `AdminRoot` around your tree.
28
+ Import the stylesheet once at your entry point, then mount `AdminRoot` around
29
+ your tree.
57
30
 
58
31
  ```tsx
59
32
  import '@gopherium/godmin/base.css'
@@ -66,287 +39,48 @@ createRoot(document.getElementById('app')!).render(
66
39
  )
67
40
  ```
68
41
 
69
- That is the whole host setup. `base.css` loads the design tokens for you, so
70
- you do not import `@wordpress/theme/design-tokens.css` separately, and it
71
- declares the cascade layer order as `wp-ui, godmin`. `AdminRoot` isolates the
72
- stacking context that portaled popovers need and enables the overlay slot that
73
- lets design system overlays stack above `@wordpress/components` ones.
74
-
75
- ### Overriding the appearance defaults
76
-
77
- `base.css` sets the page font, colour and background from design tokens inside
78
- `@layer godmin`, so any unlayered rule of your own wins without a specificity
79
- fight. One rule it deliberately leaves unlayered is `body { position: relative }`,
80
- because overlays position against the nearest positioned ancestor and an
81
- application that overrode it would get broken backdrops.
82
-
83
- If you declare your own layers, name GodMin's in the order you want:
42
+ That is the whole host setup. See
43
+ [the overview](https://docs.gopherium.org/admin-ui/overview/) for what those
44
+ two lines do for you.
84
45
 
85
- ```css
86
- @layer wp-ui, godmin, my-app;
87
- ```
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
- ### While data loads
140
-
141
- `LoadingScreen` stands in for a screen whose data has not arrived, and
142
- `LoadingRows` stands in for a list body under chrome that is already there.
143
- Both render a ghost built from the design system skeleton and announce their
144
- label through a visually hidden status region, so give `label` the same
145
- sentence you would have rendered as text.
146
-
147
- ```tsx
148
- if (reports.isPending) {
149
- return <LoadingRows label="Loading reports." rows={8} />
150
- }
151
- return <ReportTable className="godmin-arrival" />
152
- ```
153
-
154
- A ghost fades in after a short delay, so a fast load never shows one.
155
- Give the content that replaces a ghost the `godmin-arrival` class and it
156
- fades in too, so the swap reads as one motion rather than a snap.
157
-
158
- `base.css` also ships `godmin-empty`, `godmin-form`, `godmin-table` and
159
- `godmin-table-scroll`. The last two go together: a table wider than a phone
160
- scrolls inside its own region rather than dragging the page sideways.
161
-
162
- ```tsx
163
- <div className="godmin-table-scroll" role="region" aria-label="Reports" tabIndex={0}>
164
- <table className="godmin-table">…</table>
165
- </div>
166
- ```
167
-
168
- The region is focusable so a keyboard can reach the columns that scrolled out
169
- of view, and it establishes a containing block, without which absolutely
170
- positioned content inside it escapes the clip and widens the document.
171
-
172
- ### Reading the canvas from routes
173
-
174
- With TanStack Router, `@gopherium/godmin/router` lets a route declare how it
175
- fills the canvas, and the deepest route that declares one wins, so a child can
176
- opt back to a padded canvas its section left behind.
177
-
178
- ```tsx
179
- createRoute({ path: 'threads/$id', staticData: { canvas: 'bleed' } })
180
-
181
- const mode = useCanvas()
182
- const pathname = useFrameLocation()
183
- ```
184
-
185
- ### Raising messages
186
-
187
- `Toaster` holds messages a screen raises, each with an optional action.
188
-
189
- ```tsx
190
- <Toaster>
191
- <YourApp />
192
- </Toaster>
193
-
194
- const toaster = useToaster()
195
- toaster.show('Post moved to trash', { label: 'Undo', onAct: restore })
196
- ```
197
-
198
- ### Rendering into an iframe
199
-
200
- Design system styles are injected per document, so a secondary document such as
201
- an iframe or a popup needs registering. `useTokenDocument` does that and keeps
202
- it supplied with styles registered later, which is what an embedded editor
203
- canvas needs.
204
-
205
- ```tsx
206
- useTokenDocument(iframeRef.current?.contentDocument)
207
- ```
208
-
209
- ## Testing
210
-
211
- `@gopherium/godmin/testing` solves the problems the design system creates for a
212
- test runner. Call it once from your setup file.
213
-
214
- ```ts
215
- import { installTestEnvironment } from '@gopherium/godmin/testing'
216
-
217
- installTestEnvironment()
218
- ```
219
-
220
- The design system announces through `@wordpress/a11y`, which appends a live
221
- region and an intro paragraph to the body. Without this, every query for text
222
- that was also announced finds two nodes, and the last announcement of one test
223
- is still in the DOM for the next one. `installTestEnvironment` makes queries
224
- ignore those elements and empties them after each test.
225
-
226
- Because the announcement regions are then invisible to queries, read them
227
- directly instead.
228
-
229
- ```ts
230
- import { getAnnouncement } from '@gopherium/godmin/testing'
231
-
232
- speak('Draft saved')
233
- expect(getAnnouncement()).toBe('Draft saved')
234
- ```
235
-
236
- `renderAdmin` renders a tree inside `AdminRoot`, so components that read design
237
- tokens behave as they will in the application.
238
-
239
- A test runner evaluates no media queries, so `setViewport` says what they
240
- should report and tells any listener the viewport changed. That is how a test
241
- renders the narrow shell.
242
-
243
- ```ts
244
- import { setViewport } from '@gopherium/godmin/testing'
245
-
246
- setViewport({ matches: true })
247
- ```
248
-
249
- It resets before the next test, along with the rendered tree, which a runner
250
- without globals never clears by itself.
251
-
252
- `@testing-library/react` and `vitest` are optional peers, needed only for this
253
- entry point.
254
-
255
- ## Build configuration
256
-
257
- Several packages break when a bundle contains two copies of them. React is the
258
- loud case, where hooks throw, but a second `@wordpress/theme` silently gives you
259
- a second context and unthemed components. `@gopherium/godmin/vite` exports the
260
- list and a plugin that fails the build rather than shipping the bug.
261
-
262
- ```ts
263
- import { godminDedupe, godminSingleCopy } from '@gopherium/godmin/vite'
264
-
265
- export default defineConfig({
266
- resolve: { dedupe: godminDedupe },
267
- plugins: [godminSingleCopy()],
268
- })
269
- ```
270
-
271
- The list cannot live in the package alone, because `resolve.dedupe` is read
272
- from your own config, so GodMin ships it as data for you to spread.
273
-
274
- Dedupe settles which copy your bundler picks, but it cannot stop a second one
275
- being installed. `@wordpress/element` up to 8.4.0 declares React 18 as a
276
- dependency rather than a peer, so a fresh install materialises React 18 beside
277
- your React 19 and the first hook throws `Cannot read properties of null`. Pin
278
- the version yourself.
279
-
280
- ```json
281
- {
282
- "pnpm": {
283
- "overrides": { "react": "^19.2.0", "react-dom": "^19.2.0" }
284
- }
285
- }
286
- ```
287
-
288
- ## React 19 and @wordpress/element
289
-
290
- Up to and including 8.4.0, `@wordpress/element` imports APIs that React 19
291
- removed, so it fails to load. The fix is a patch, and pnpm applies patches at
292
- install time before `node_modules` exists, so no published package can supply
293
- one for you. GodMin ships the patch it was tested against for you to copy.
294
-
295
- ```sh
296
- cp node_modules/@gopherium/godmin/patches/*.patch patches/
297
- ```
298
-
299
- ```yaml
300
- patchedDependencies:
301
- '@wordpress/element@8.4.0': patches/@wordpress__element@8.4.0.patch
302
- ```
303
-
304
- Rather than checking that your patch file matches ours, assert the outcome in
305
- your test suite, which is what actually determines whether your application
306
- runs.
307
-
308
- ```ts
309
- import { assertElementPatched } from '@gopherium/godmin/testing'
310
-
311
- test('element works on React 19', async () => {
312
- await assertElementPatched()
313
- })
314
- ```
46
+ ## What is in it
315
47
 
316
- **This is temporary.** The fix is merged upstream and lands in a future
317
- `@wordpress/element` release, after which no patch is needed at all. The
318
- assertion is written for that: it checks that the removed APIs are absent and
319
- the live ones work, so it keeps passing once upstream ships and the patch goes
320
- away, whether that arrives as a minor or a major.
48
+ | Entry point | Contents |
49
+ | --- | --- |
50
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `NavScreen`, `ErrorNotice`, `LoadMore`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `useMediaQuery`, `useTokenDocument`, the breakpoints, `SUPPORTED_WPDS` |
51
+ | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
52
+ | `@gopherium/godmin/router` | `useCanvas`, `useFrameLocation`, the `canvas` route static data |
53
+ | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport`, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR` |
54
+ | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `duplicateCopies` |
55
+ | `@gopherium/godmin/stylelint` | The design system stylelint rules |
56
+ | `@gopherium/godmin/patches/*` | The React 19 patch file for `@wordpress/element`, copied at install time, temporary |
321
57
 
322
- GodMin does not constrain your `@wordpress/element` version. It never imports
323
- it at runtime, and the version is chosen by `@wordpress/ui` and
324
- `@wordpress/theme`, which depend on it directly. The shipped patch file is
325
- removed from this package once the fixed release is the one those packages
326
- resolve.
58
+ ## Before your first build
327
59
 
328
- ## Linting your stylesheets
60
+ Two install-time problems stop the application booting, and neither error
61
+ points at its cause. Both are covered in
62
+ [build configuration](https://docs.gopherium.org/admin-ui/build-and-versioning/).
329
63
 
330
- `@wordpress/theme` ships three stylelint rules and turning them on requires
331
- knowing they exist and what they are called. `@gopherium/godmin/stylelint` is
332
- that configuration.
64
+ - **Duplicate packages.** Two copies of React throw on the first hook, and two
65
+ copies of `@wordpress/theme` render unthemed components silently. Spread
66
+ `godminDedupe` into `resolve.dedupe` and add the `godminSingleCopy()` plugin.
67
+ - **React 19.** `@wordpress/element` up to 8.4.0 fails to load on React 19.
68
+ Copy the patch this package ships into your own `patches/` directory, since
69
+ pnpm applies patches before `node_modules` exists.
333
70
 
334
- ```js
335
- export default { extends: ['@gopherium/godmin/stylelint'] }
336
- ```
71
+ ## Design system versions
337
72
 
338
- It catches design tokens that do not exist, an application redefining a
339
- `--wpds-` property, and hand written fallback values. The first of those is the
340
- one that bites quietly, since a mistyped token renders nothing at all.
341
- `stylelint` is an optional peer, needed only for this entry point.
73
+ Peer ranges are longhand and single window, for example `>=0.19.0 <0.20.0`.
74
+ The window moves with each design system release train and never widens, so no
75
+ release accepts two breaking generations at once. `SUPPORTED_WPDS` exports the
76
+ window this build was tested against.
342
77
 
343
- ## Design system version policy
78
+ ## Status
344
79
 
345
- Peer ranges are longhand and single window, for example `>=0.19.0 <0.20.0`. The
346
- window MOVES on each design system train bump and never widens, so no release
347
- accepts two breaking generations at once. `@wordpress/ui` is pre 1.0, where a
348
- caret range covers only one minor, and reading a caret as broader than that is
349
- what silently breaks consumers.
80
+ Still 0.x, so minor releases may break. See the CHANGELOG for what each release
81
+ adds. `@wordpress/admin-ui` remains the thing to watch: GodMin does not wrap
82
+ it, because a kit that wraps an API still moving adds a release hop to every
83
+ upstream fix.
350
84
 
351
85
  ## License
352
86
 
package/dist/vite.d.ts CHANGED
@@ -9,6 +9,23 @@ export declare const godminDedupe: string[];
9
9
  * @returns A map of package name to the distinct roots it resolved to.
10
10
  */
11
11
  export declare function duplicateCopies(moduleIds: Iterable<string>, packages: string[]): Map<string, string[]>;
12
+ /**
13
+ * Returns the page with its stylesheets moved above the first module script.
14
+ * @param html - The built page source.
15
+ * @returns The page source, stylesheets first.
16
+ */
17
+ export declare function hoistStylesheet(html: string): string;
18
+ /**
19
+ * Returns a bundler plugin requesting the stylesheet before the module script.
20
+ * @returns The plugin to add to the bundler configuration.
21
+ */
22
+ export declare function godminStylesheetFirst(): {
23
+ name: string;
24
+ transformIndexHtml: {
25
+ order: "post";
26
+ handler: typeof hoistStylesheet;
27
+ };
28
+ };
12
29
  /**
13
30
  * The subset of the bundler context this plugin reads.
14
31
  */
@@ -21,9 +38,6 @@ interface BuildContext {
21
38
  */
22
39
  export declare function godminSingleCopy(): {
23
40
  name: string;
24
- /**
25
- * Fails the build when a package that must be a singleton resolved twice.
26
- */
27
41
  buildEnd(this: BuildContext): void;
28
42
  };
29
43
  export {};
package/dist/vite.js CHANGED
@@ -8,6 +8,7 @@ export const godminDedupe = [
8
8
  '@wordpress/element',
9
9
  '@wordpress/theme',
10
10
  '@wordpress/ui',
11
+ '@gopherium/react-auth',
11
12
  ];
12
13
  /**
13
14
  * Returns the package a resolved module id belongs to.
@@ -44,6 +45,37 @@ export function duplicateCopies(moduleIds, packages) {
44
45
  }
45
46
  return duplicates;
46
47
  }
48
+ const STYLESHEET = /[ \t]*<link[^>]+rel="stylesheet"[^>]*>\n?/g;
49
+ const MODULE_SCRIPT = /[ \t]*<script[^>]+type="module"[^>]*><\/script>/;
50
+ /**
51
+ * Returns the page with its stylesheets moved above the first module script.
52
+ * @param html - The built page source.
53
+ * @returns The page source, stylesheets first.
54
+ */
55
+ export function hoistStylesheet(html) {
56
+ const sheets = html.match(STYLESHEET);
57
+ const script = html.match(MODULE_SCRIPT);
58
+ if (sheets === null || script === null || script.index === undefined) {
59
+ return html;
60
+ }
61
+ if (html.indexOf(sheets[0]) < script.index) {
62
+ return html;
63
+ }
64
+ return html.replace(STYLESHEET, '').replace(MODULE_SCRIPT, sheets.join('') + script[0]);
65
+ }
66
+ /**
67
+ * Returns a bundler plugin requesting the stylesheet before the module script.
68
+ * @returns The plugin to add to the bundler configuration.
69
+ */
70
+ export function godminStylesheetFirst() {
71
+ return {
72
+ name: 'godmin-stylesheet-first',
73
+ transformIndexHtml: {
74
+ order: 'post',
75
+ handler: hoistStylesheet,
76
+ },
77
+ };
78
+ }
47
79
  /**
48
80
  * Returns a bundler plugin failing the build when a singleton package is duplicated.
49
81
  * @returns The plugin to add to the bundler configuration.
@@ -51,9 +83,6 @@ export function duplicateCopies(moduleIds, packages) {
51
83
  export function godminSingleCopy() {
52
84
  return {
53
85
  name: 'godmin-single-copy',
54
- /**
55
- * Fails the build when a package that must be a singleton resolved twice.
56
- */
57
86
  buildEnd() {
58
87
  const duplicates = duplicateCopies(this.getModuleIds(), godminDedupe);
59
88
  if (duplicates.size === 0) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gopherium/godmin",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
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",