@gopherium/godmin 0.1.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/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,12 @@
1
+ GodMin
2
+ Copyright 2026 The GodMin Authors
3
+
4
+ This product includes software developed at the Gopherium project
5
+ (https://github.com/gopherium).
6
+
7
+ Applications built with GodMin resolve the WordPress Design System packages
8
+ (@wordpress/ui, @wordpress/theme and their dependencies) themselves. Those
9
+ packages are licensed GPL-2.0-or-later with a dual MPL-2.0 grant on
10
+ contributions made after 2021. GodMin's own source is Apache-2.0 and declares
11
+ those packages as peer dependencies, so it never redistributes them. A bundle
12
+ that combines them is conveyed under the terms of the WordPress packages.
package/README.md ADDED
@@ -0,0 +1,216 @@
1
+ # GodMin
2
+
3
+ Gopherium's admin kit
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.
12
+
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.
17
+
18
+ ## What is in it
19
+
20
+ | Entry point | Contents |
21
+ | --- | --- |
22
+ | `@gopherium/godmin` | `AdminRoot`, `useTokenDocument`, `SUPPORTED_WPDS` |
23
+ | `@gopherium/godmin/base.css` | cascade layer order, design tokens, host rules |
24
+ | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR` |
25
+ | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy` |
26
+ | `@gopherium/godmin/stylelint` | the design system stylelint rules |
27
+ | `@gopherium/godmin/patches` | the React 19 patch for `@wordpress/element`, temporary |
28
+
29
+ ## Status
30
+
31
+ Version 0.1.0 is the host layer. The application frame is deliberately not here
32
+ yet, because `@wordpress/admin-ui` is actively building that layer and a kit
33
+ should not race upstream. See the CHANGELOG for what each release adds.
34
+
35
+ ## Install
36
+
37
+ ```sh
38
+ pnpm add @gopherium/godmin
39
+ ```
40
+
41
+ GodMin declares the design system as peer dependencies, so your application
42
+ resolves and pins them. The window this build was tested against is exported as
43
+ `SUPPORTED_WPDS` and enforced by the declared peer ranges.
44
+
45
+ ## Setup
46
+
47
+ Import the stylesheet once, at your application entry point, then mount
48
+ `AdminRoot` around your tree.
49
+
50
+ ```tsx
51
+ import '@gopherium/godmin/base.css'
52
+ import { AdminRoot } from '@gopherium/godmin'
53
+
54
+ createRoot(document.getElementById('app')!).render(
55
+ <AdminRoot>
56
+ <YourApp />
57
+ </AdminRoot>,
58
+ )
59
+ ```
60
+
61
+ That is the whole host setup. `base.css` loads the design tokens for you, so
62
+ you do not import `@wordpress/theme/design-tokens.css` separately, and it
63
+ declares the cascade layer order as `wp-ui, godmin`. `AdminRoot` isolates the
64
+ stacking context that portaled popovers need and enables the overlay slot that
65
+ lets design system overlays stack above `@wordpress/components` ones.
66
+
67
+ ### Overriding the appearance defaults
68
+
69
+ `base.css` sets the page font, colour and background from design tokens inside
70
+ `@layer godmin`, so any unlayered rule of your own wins without a specificity
71
+ fight. One rule it deliberately leaves unlayered is `body { position: relative }`,
72
+ because overlays position against the nearest positioned ancestor and an
73
+ application that overrode it would get broken backdrops.
74
+
75
+ If you declare your own layers, name GodMin's in the order you want:
76
+
77
+ ```css
78
+ @layer wp-ui, godmin, my-app;
79
+ ```
80
+
81
+ ### Rendering into an iframe
82
+
83
+ Design system styles are injected per document, so a secondary document such as
84
+ an iframe or a popup needs registering. `useTokenDocument` does that and keeps
85
+ it supplied with styles registered later, which is what an embedded editor
86
+ canvas needs.
87
+
88
+ ```tsx
89
+ useTokenDocument(iframeRef.current?.contentDocument)
90
+ ```
91
+
92
+ ## Testing
93
+
94
+ `@gopherium/godmin/testing` solves the problems the design system creates for a
95
+ test runner. Call it once from your setup file.
96
+
97
+ ```ts
98
+ import { installTestEnvironment } from '@gopherium/godmin/testing'
99
+
100
+ installTestEnvironment()
101
+ ```
102
+
103
+ The design system announces through `@wordpress/a11y`, which appends a live
104
+ region and an intro paragraph to the body. Without this, every query for text
105
+ that was also announced finds two nodes, and the last announcement of one test
106
+ is still in the DOM for the next one. `installTestEnvironment` makes queries
107
+ ignore those elements and empties them after each test.
108
+
109
+ Because the announcement regions are then invisible to queries, read them
110
+ directly instead.
111
+
112
+ ```ts
113
+ import { getAnnouncement } from '@gopherium/godmin/testing'
114
+
115
+ speak('Draft saved')
116
+ expect(getAnnouncement()).toBe('Draft saved')
117
+ ```
118
+
119
+ `renderAdmin` renders a tree inside `AdminRoot`, so components that read design
120
+ tokens behave as they will in the application.
121
+
122
+ `@testing-library/react` and `vitest` are optional peers, needed only for this
123
+ entry point.
124
+
125
+ ## Build configuration
126
+
127
+ Several packages break when a bundle contains two copies of them. React is the
128
+ loud case, where hooks throw, but a second `@wordpress/theme` silently gives you
129
+ a second context and unthemed components. `@gopherium/godmin/vite` exports the
130
+ list and a plugin that fails the build rather than shipping the bug.
131
+
132
+ ```ts
133
+ import { godminDedupe, godminSingleCopy } from '@gopherium/godmin/vite'
134
+
135
+ export default defineConfig({
136
+ resolve: { dedupe: godminDedupe },
137
+ plugins: [godminSingleCopy()],
138
+ })
139
+ ```
140
+
141
+ The list cannot live in the package alone, because `resolve.dedupe` is read
142
+ from your own config, so GodMin ships it as data for you to spread.
143
+
144
+ ## React 19 and @wordpress/element
145
+
146
+ Up to and including 8.4.0, `@wordpress/element` imports APIs that React 19
147
+ removed, so it fails to load. The fix is a patch, and pnpm applies patches at
148
+ install time before `node_modules` exists, so no published package can supply
149
+ one for you. GodMin ships the patch it was tested against for you to copy.
150
+
151
+ ```sh
152
+ cp node_modules/@gopherium/godmin/patches/*.patch patches/
153
+ ```
154
+
155
+ ```yaml
156
+ patchedDependencies:
157
+ '@wordpress/element@8.4.0': patches/@wordpress__element@8.4.0.patch
158
+ ```
159
+
160
+ Rather than checking that your patch file matches ours, assert the outcome in
161
+ your test suite, which is what actually determines whether your application
162
+ runs.
163
+
164
+ ```ts
165
+ import { assertElementPatched } from '@gopherium/godmin/testing'
166
+
167
+ test('element works on React 19', async () => {
168
+ await assertElementPatched()
169
+ })
170
+ ```
171
+
172
+ **This is temporary.** The fix is merged upstream and lands in a future
173
+ `@wordpress/element` release, after which no patch is needed at all. The
174
+ assertion is written for that: it checks that the removed APIs are absent and
175
+ the live ones work, so it keeps passing once upstream ships and the patch goes
176
+ away, whether that arrives as a minor or a major.
177
+
178
+ GodMin does not constrain your `@wordpress/element` version. It never imports
179
+ it at runtime, and the version is chosen by `@wordpress/ui` and
180
+ `@wordpress/theme`, which depend on it directly. The shipped patch file is
181
+ removed from this package once the fixed release is the one those packages
182
+ resolve.
183
+
184
+ ## Linting your stylesheets
185
+
186
+ `@wordpress/theme` ships three stylelint rules and turning them on requires
187
+ knowing they exist and what they are called. `@gopherium/godmin/stylelint` is
188
+ that configuration.
189
+
190
+ ```js
191
+ export default { extends: ['@gopherium/godmin/stylelint'] }
192
+ ```
193
+
194
+ It catches design tokens that do not exist, an application redefining a
195
+ `--wpds-` property, and hand written fallback values. The first of those is the
196
+ one that bites quietly, since a mistyped token renders nothing at all.
197
+ `stylelint` is an optional peer, needed only for this entry point.
198
+
199
+ ## Design system version policy
200
+
201
+ Peer ranges are longhand and single window, for example `>=0.19.0 <0.20.0`. The
202
+ window MOVES on each design system train bump and never widens, so no release
203
+ accepts two breaking generations at once. `@wordpress/ui` is pre 1.0, where a
204
+ caret range covers only one minor, and reading a caret as broader than that is
205
+ what silently breaks consumers.
206
+
207
+ ## License
208
+
209
+ Apache-2.0, see LICENSE.
210
+
211
+ The design system packages this kit expects you to install are
212
+ GPL-2.0-or-later. GodMin declares them as peer dependencies, so your
213
+ application resolves them and GodMin never redistributes them. Your built
214
+ bundle combines both, and is conveyed under the terms of the WordPress
215
+ packages. GodMin's own source stays reusable under plain Apache-2.0. NOTICE
216
+ carries the same statement for anyone reading only the published tarball.
@@ -0,0 +1,14 @@
1
+ import { ThemeProvider } from '@wordpress/theme';
2
+ import type { ComponentProps, ElementType, ReactNode } from 'react';
3
+ type ThemeSettings = Pick<ComponentProps<typeof ThemeProvider>, 'color' | 'cursor' | 'cornerRadius'>;
4
+ export interface AdminRootProps extends ThemeSettings {
5
+ children: ReactNode;
6
+ as?: ElementType;
7
+ }
8
+ /**
9
+ * Hosts a design system application in its own stacking context.
10
+ * @param props - The theme settings, root element type and children.
11
+ * @returns The host element wrapping the themed children.
12
+ */
13
+ export declare function AdminRoot({ children, as: Root, ...theme }: AdminRootProps): import("react").JSX.Element;
14
+ export {};
@@ -0,0 +1,13 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { ThemeProvider } from '@wordpress/theme';
4
+ import { useEnableWpCompatOverlaySlot } from '@wordpress/ui';
5
+ /**
6
+ * Hosts a design system application in its own stacking context.
7
+ * @param props - The theme settings, root element type and children.
8
+ * @returns The host element wrapping the themed children.
9
+ */
10
+ export function AdminRoot({ children, as: Root = 'div', ...theme }) {
11
+ useEnableWpCompatOverlaySlot();
12
+ return (_jsx(Root, { style: { isolation: 'isolate' }, children: _jsx(ThemeProvider, { ...theme, isRoot: true, children: children }) }));
13
+ }
package/dist/base.css ADDED
@@ -0,0 +1,22 @@
1
+ /* SPDX-License-Identifier: Apache-2.0 */
2
+
3
+ @layer wp-ui, godmin;
4
+
5
+ @import '@wordpress/theme/design-tokens.css';
6
+
7
+ /*
8
+ * Overlay elements position themselves against the nearest positioned ancestor,
9
+ * so this rule is unlayered and outranks application styles.
10
+ */
11
+ body {
12
+ position: relative;
13
+ }
14
+
15
+ @layer godmin {
16
+ body {
17
+ margin: 0;
18
+ font-family: var(--wpds-typography-font-family-body);
19
+ color: var(--wpds-color-foreground-content-neutral);
20
+ background: var(--wpds-color-background-surface-neutral);
21
+ }
22
+ }
@@ -0,0 +1,10 @@
1
+ export { AdminRoot } from './admin-root.js';
2
+ export type { AdminRootProps } from './admin-root.js';
3
+ export { useTokenDocument } from './use-token-document.js';
4
+ /**
5
+ * The design system version window this build was tested against.
6
+ */
7
+ export declare const SUPPORTED_WPDS: {
8
+ readonly '@wordpress/ui': ">=0.19.0 <0.20.0";
9
+ readonly '@wordpress/theme': ">=1.1.0 <2.0.0";
10
+ };
package/dist/index.js ADDED
@@ -0,0 +1,10 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ export { AdminRoot } from './admin-root.js';
3
+ export { useTokenDocument } from './use-token-document.js';
4
+ /**
5
+ * The design system version window this build was tested against.
6
+ */
7
+ export const SUPPORTED_WPDS = {
8
+ '@wordpress/ui': '>=0.19.0 <0.20.0',
9
+ '@wordpress/theme': '>=1.1.0 <2.0.0',
10
+ };
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The stylelint configuration turning on every design system rule the theme
3
+ * package ships.
4
+ */
5
+ declare const config: {
6
+ plugins: string[];
7
+ rules: {
8
+ 'plugin-wpds/no-unknown-ds-tokens': boolean;
9
+ 'plugin-wpds/no-setting-wpds-custom-properties': boolean;
10
+ 'plugin-wpds/no-token-fallback-values': boolean;
11
+ };
12
+ };
13
+ export default config;
@@ -0,0 +1,18 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ /**
3
+ * The stylelint configuration turning on every design system rule the theme
4
+ * package ships.
5
+ */
6
+ const config = {
7
+ plugins: [
8
+ '@wordpress/theme/stylelint-plugins/no-unknown-ds-tokens',
9
+ '@wordpress/theme/stylelint-plugins/no-setting-wpds-custom-properties',
10
+ '@wordpress/theme/stylelint-plugins/no-token-fallback-values',
11
+ ],
12
+ rules: {
13
+ 'plugin-wpds/no-unknown-ds-tokens': true,
14
+ 'plugin-wpds/no-setting-wpds-custom-properties': true,
15
+ 'plugin-wpds/no-token-fallback-values': true,
16
+ },
17
+ };
18
+ export default config;
@@ -0,0 +1,41 @@
1
+ import type { RenderOptions, RenderResult } from '@testing-library/react';
2
+ import type { ReactNode } from 'react';
3
+ import type { AdminRootProps } from './admin-root.js';
4
+ /**
5
+ * The elements the design system announces through rather than displays.
6
+ */
7
+ export declare const WPDS_IGNORE_SELECTOR = "script, style, [id^=\"a11y-speak\"]";
8
+ /**
9
+ * The urgency an announcement was made with.
10
+ */
11
+ export type Politeness = 'polite' | 'assertive';
12
+ /**
13
+ * Returns the message currently announced at the given urgency.
14
+ * @param politeness - The urgency to read, polite by default.
15
+ * @returns The announced message, or an empty string when there is none.
16
+ */
17
+ export declare function getAnnouncement(politeness?: Politeness): string;
18
+ /**
19
+ * Empties every announcement region.
20
+ */
21
+ export declare function clearAnnouncements(): void;
22
+ /**
23
+ * Loads a module by specifier.
24
+ */
25
+ export type LoadModule = () => Promise<Record<string, unknown>>;
26
+ /**
27
+ * Asserts `@wordpress/element` works on React 19.
28
+ * @param load - The loader for the element module, its own import by default.
29
+ */
30
+ export declare function assertElementPatched(load?: LoadModule): Promise<void>;
31
+ /**
32
+ * Prepares the test environment a design system application needs.
33
+ */
34
+ export declare function installTestEnvironment(): void;
35
+ /**
36
+ * Renders the given tree inside the design system host.
37
+ * @param ui - The tree to render.
38
+ * @param options - The testing library options, plus the host theme settings.
39
+ * @returns The testing library render result.
40
+ */
41
+ export declare function renderAdmin(ui: ReactNode, options?: RenderOptions & Omit<AdminRootProps, 'children'>): RenderResult;
@@ -0,0 +1,78 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { configure, render } from '@testing-library/react';
4
+ import { afterEach } from 'vitest';
5
+ import { AdminRoot } from './admin-root.js';
6
+ /**
7
+ * The elements the design system announces through rather than displays.
8
+ */
9
+ export const WPDS_IGNORE_SELECTOR = 'script, style, [id^="a11y-speak"]';
10
+ /**
11
+ * Returns the message currently announced at the given urgency.
12
+ * @param politeness - The urgency to read, polite by default.
13
+ * @returns The announced message, or an empty string when there is none.
14
+ */
15
+ export function getAnnouncement(politeness = 'polite') {
16
+ return document.getElementById(`a11y-speak-${politeness}`)?.textContent ?? '';
17
+ }
18
+ /**
19
+ * Empties every announcement region.
20
+ */
21
+ export function clearAnnouncements() {
22
+ for (const region of document.querySelectorAll('[id^="a11y-speak"]')) {
23
+ region.textContent = '';
24
+ }
25
+ }
26
+ /**
27
+ * The APIs React 19 removed, which `@wordpress/element` must no longer provide.
28
+ */
29
+ const REMOVED_BY_REACT_19 = ['findDOMNode', 'render', 'hydrate', 'unmountComponentAtNode'];
30
+ /**
31
+ * The APIs `@wordpress/element` must still provide.
32
+ */
33
+ const STILL_PROVIDED = ['createRoot', 'createPortal'];
34
+ /**
35
+ * Asserts `@wordpress/element` works on React 19.
36
+ * @param load - The loader for the element module, its own import by default.
37
+ */
38
+ export async function assertElementPatched(load = () => import('@wordpress/element')) {
39
+ let element;
40
+ try {
41
+ element = await load();
42
+ }
43
+ catch (cause) {
44
+ throw new Error('@wordpress/element could not be imported, which is what an unpatched build does on React 19', { cause });
45
+ }
46
+ for (const name of REMOVED_BY_REACT_19) {
47
+ if (element[name] !== undefined) {
48
+ throw new Error(`@wordpress/element still provides ${name}, which React 19 removed`);
49
+ }
50
+ }
51
+ for (const name of STILL_PROVIDED) {
52
+ if (typeof element[name] !== 'function') {
53
+ throw new Error(`@wordpress/element does not provide ${name}`);
54
+ }
55
+ }
56
+ }
57
+ /**
58
+ * Prepares the test environment a design system application needs.
59
+ */
60
+ export function installTestEnvironment() {
61
+ configure({ defaultIgnore: WPDS_IGNORE_SELECTOR });
62
+ afterEach(clearAnnouncements);
63
+ }
64
+ /**
65
+ * Renders the given tree inside the design system host.
66
+ * @param ui - The tree to render.
67
+ * @param options - The testing library options, plus the host theme settings.
68
+ * @returns The testing library render result.
69
+ */
70
+ export function renderAdmin(ui, options = {}) {
71
+ const { color, cursor, cornerRadius, as, ...renderOptions } = options;
72
+ return render(ui, {
73
+ ...renderOptions,
74
+ wrapper: function Host({ children }) {
75
+ return _jsx(AdminRoot, { color, cursor, cornerRadius, as, children: children });
76
+ },
77
+ });
78
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Keeps the given document supplied with the design system styles.
3
+ * @param target - The document to register, or nothing while it is unavailable.
4
+ */
5
+ export declare function useTokenDocument(target: Document | null | undefined): void;
@@ -0,0 +1,15 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { registerDocument } from '@wordpress/style-runtime';
3
+ import { useEffect } from 'react';
4
+ /**
5
+ * Keeps the given document supplied with the design system styles.
6
+ * @param target - The document to register, or nothing while it is unavailable.
7
+ */
8
+ export function useTokenDocument(target) {
9
+ useEffect(() => {
10
+ if (!target) {
11
+ return;
12
+ }
13
+ return registerDocument(target);
14
+ }, [target]);
15
+ }
package/dist/vite.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The packages that must resolve to a single copy in an application bundle.
3
+ */
4
+ export declare const godminDedupe: string[];
5
+ /**
6
+ * Returns each watched package that resolved to more than one file tree.
7
+ * @param moduleIds - The resolved module ids in the bundle.
8
+ * @param packages - The package names that must be singletons.
9
+ * @returns A map of package name to the distinct roots it resolved to.
10
+ */
11
+ export declare function duplicateCopies(moduleIds: Iterable<string>, packages: string[]): Map<string, string[]>;
12
+ /**
13
+ * The subset of the bundler context this plugin reads.
14
+ */
15
+ interface BuildContext {
16
+ getModuleIds: () => Iterable<string>;
17
+ }
18
+ /**
19
+ * Returns a bundler plugin failing the build when a singleton package is duplicated.
20
+ * @returns The plugin to add to the bundler configuration.
21
+ */
22
+ export declare function godminSingleCopy(): {
23
+ name: string;
24
+ /**
25
+ * Fails the build when a package that must be a singleton resolved twice.
26
+ */
27
+ buildEnd(this: BuildContext): void;
28
+ };
29
+ export {};
package/dist/vite.js ADDED
@@ -0,0 +1,68 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ /**
3
+ * The packages that must resolve to a single copy in an application bundle.
4
+ */
5
+ export const godminDedupe = [
6
+ 'react',
7
+ 'react-dom',
8
+ '@wordpress/element',
9
+ '@wordpress/theme',
10
+ '@wordpress/ui',
11
+ ];
12
+ /**
13
+ * Returns the package a resolved module id belongs to.
14
+ * @param id - The resolved module id to inspect.
15
+ * @param packages - The package names to look for.
16
+ * @returns The matching package name, or nothing when the id belongs to none.
17
+ */
18
+ function packageOf(id, packages) {
19
+ return packages.find((name) => id.includes(`/node_modules/${name}/`));
20
+ }
21
+ /**
22
+ * Returns each watched package that resolved to more than one file tree.
23
+ * @param moduleIds - The resolved module ids in the bundle.
24
+ * @param packages - The package names that must be singletons.
25
+ * @returns A map of package name to the distinct roots it resolved to.
26
+ */
27
+ export function duplicateCopies(moduleIds, packages) {
28
+ const roots = new Map();
29
+ for (const id of moduleIds) {
30
+ const name = packageOf(id, packages);
31
+ if (name === undefined) {
32
+ continue;
33
+ }
34
+ const root = id.slice(0, id.indexOf(`/node_modules/${name}/`) + `/node_modules/${name}/`.length);
35
+ const seen = roots.get(name) ?? new Set();
36
+ seen.add(root);
37
+ roots.set(name, seen);
38
+ }
39
+ const duplicates = new Map();
40
+ for (const [name, seen] of roots) {
41
+ if (seen.size > 1) {
42
+ duplicates.set(name, [...seen]);
43
+ }
44
+ }
45
+ return duplicates;
46
+ }
47
+ /**
48
+ * Returns a bundler plugin failing the build when a singleton package is duplicated.
49
+ * @returns The plugin to add to the bundler configuration.
50
+ */
51
+ export function godminSingleCopy() {
52
+ return {
53
+ name: 'godmin-single-copy',
54
+ /**
55
+ * Fails the build when a package that must be a singleton resolved twice.
56
+ */
57
+ buildEnd() {
58
+ const duplicates = duplicateCopies(this.getModuleIds(), godminDedupe);
59
+ if (duplicates.size === 0) {
60
+ return;
61
+ }
62
+ const report = [...duplicates]
63
+ .map(([name, roots]) => `${name} resolved to ${roots.length} copies:\n ${roots.join('\n ')}`)
64
+ .join('\n');
65
+ throw new Error(`godmin: these packages must resolve to one copy.\n${report}`);
66
+ },
67
+ };
68
+ }
package/package.json ADDED
@@ -0,0 +1,98 @@
1
+ {
2
+ "name": "@gopherium/godmin",
3
+ "version": "0.1.0",
4
+ "description": "The admin kit for Gopherium projects: host layer for React admin applications on the WordPress Design System.",
5
+ "license": "Apache-2.0",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/gopherium/godmin.git"
10
+ },
11
+ "keywords": [
12
+ "admin",
13
+ "wordpress",
14
+ "design-system",
15
+ "react",
16
+ "gopherium"
17
+ ],
18
+ "files": [
19
+ "dist",
20
+ "NOTICE",
21
+ "patches"
22
+ ],
23
+ "exports": {
24
+ ".": {
25
+ "types": "./dist/index.d.ts",
26
+ "default": "./dist/index.js"
27
+ },
28
+ "./base.css": "./dist/base.css",
29
+ "./patches/*": "./patches/*",
30
+ "./stylelint": {
31
+ "types": "./dist/stylelint.d.ts",
32
+ "default": "./dist/stylelint.js"
33
+ },
34
+ "./testing": {
35
+ "types": "./dist/testing.d.ts",
36
+ "default": "./dist/testing.js"
37
+ },
38
+ "./vite": {
39
+ "types": "./dist/vite.d.ts",
40
+ "default": "./dist/vite.js"
41
+ },
42
+ "./package.json": "./package.json"
43
+ },
44
+ "scripts": {
45
+ "build": "tsc -p tsconfig.build.json && cp src/base.css dist/base.css",
46
+ "cover": "vitest run --coverage",
47
+ "lint": "oxlint",
48
+ "lint:css": "stylelint 'src/**/*.css'",
49
+ "typecheck": "tsc --noEmit",
50
+ "prepublishOnly": "pnpm run build"
51
+ },
52
+ "publishConfig": {
53
+ "access": "public"
54
+ },
55
+ "peerDependencies": {
56
+ "@testing-library/react": "^16.3.2",
57
+ "@wordpress/style-runtime": ">=0.8.0 <0.9.0",
58
+ "@wordpress/theme": ">=1.1.0 <2.0.0",
59
+ "@wordpress/ui": ">=0.19.0 <0.20.0",
60
+ "react": "^19.2.0",
61
+ "stylelint": "^16 || ^17",
62
+ "vitest": "^4.1.10"
63
+ },
64
+ "peerDependenciesMeta": {
65
+ "@testing-library/react": {
66
+ "optional": true
67
+ },
68
+ "stylelint": {
69
+ "optional": true
70
+ },
71
+ "vitest": {
72
+ "optional": true
73
+ }
74
+ },
75
+ "devDependencies": {
76
+ "@testing-library/react": "^16.3.2",
77
+ "@types/node": "^26.1.2",
78
+ "@types/react": "^19.2.17",
79
+ "@vitejs/plugin-react": "^6.0.3",
80
+ "@vitest/coverage-v8": "^4.1.10",
81
+ "@wordpress/a11y": "4.52.0",
82
+ "@wordpress/element": "8.4.0",
83
+ "@wordpress/style-runtime": "0.8.0",
84
+ "@wordpress/theme": "1.1.0",
85
+ "@wordpress/ui": "0.19.0",
86
+ "eslint": "^10.7.0",
87
+ "eslint-plugin-jsdoc": "^63.2.0",
88
+ "eslint-plugin-tsdoc": "^0.5.2",
89
+ "jsdom": "^29.1.1",
90
+ "oxlint": "^1.71.0",
91
+ "react": "^19.2.8",
92
+ "react-dom": "^19.2.8",
93
+ "stylelint": "^17.0.0",
94
+ "typescript": "~6.0.2",
95
+ "typescript-eslint": "^8.65.0",
96
+ "vitest": "^4.1.10"
97
+ }
98
+ }
@@ -0,0 +1,31 @@
1
+ diff --git a/build-module/react-platform.mjs b/build-module/react-platform.mjs
2
+ index 8ed5aef770524fe83d1a0264e00f2d2f932d4f8b..882b2458878bc0881d07dead238607ed6c217dc8 100644
3
+ --- a/build-module/react-platform.mjs
4
+ +++ b/build-module/react-platform.mjs
5
+ @@ -1,13 +1,16 @@
6
+ // packages/element/src/react-platform.ts
7
+ +// Patched for React 19: findDOMNode, render, hydrate and
8
+ +// unmountComponentAtNode no longer exist in react-dom. The names stay
9
+ +// exported so importers keep loading, calling one is an error.
10
+ import {
11
+ createPortal,
12
+ - findDOMNode,
13
+ - flushSync,
14
+ - render,
15
+ - hydrate,
16
+ - unmountComponentAtNode
17
+ + flushSync
18
+ } from "react-dom";
19
+ import { createRoot, hydrateRoot } from "react-dom/client";
20
+ +const findDOMNode = undefined;
21
+ +const render = undefined;
22
+ +const hydrate = undefined;
23
+ +const unmountComponentAtNode = undefined;
24
+ export {
25
+ createPortal,
26
+ createRoot,
27
+ @@ -18,4 +21,3 @@ export {
28
+ render,
29
+ unmountComponentAtNode
30
+ };
31
+ -//# sourceMappingURL=react-platform.mjs.map