@gopherium/godmin 0.2.2 → 0.4.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
@@ -19,7 +19,7 @@ here duplicates something upstream ships.
19
19
 
20
20
  | Entry point | Contents |
21
21
  | --- | --- |
22
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `NavScreen`, `ErrorNotice`, `LoadMore`, `Toaster`, `useToaster`, `useMediaQuery`, `useTokenDocument`, the breakpoints, `SUPPORTED_WPDS` |
22
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `NavScreen`, `ErrorNotice`, `LoadMore`, `LoadingScreen`, `LoadingRows`, `useLoadingGate`, `Toaster`, `useToaster`, `useMediaQuery`, `useTokenDocument`, the breakpoints, `SUPPORTED_WPDS` |
23
23
  | `@gopherium/godmin/base.css` | cascade layer order, design tokens, host rules, frame and screen styles |
24
24
  | `@gopherium/godmin/router` | `useCanvas`, `useFrameLocation`, the `canvas` route static data |
25
25
  | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport`, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR` |
@@ -136,6 +136,27 @@ supply so the kit stays router free.
136
136
  </NavScreen>
137
137
  ```
138
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
+ const ghost = useLoadingGate(reports.isPending)
149
+
150
+ if (ghost) {
151
+ return <LoadingRows label="Loading reports." rows={8} />
152
+ }
153
+ ```
154
+
155
+ `useLoadingGate` owns the timing: a load that resolves quickly shows no
156
+ ghost at all, and a ghost that does appear stays long enough to read as
157
+ intentional. Gate the pending flag rather than using it directly, or a
158
+ mid speed load flashes the ghost for a moment.
159
+
139
160
  `base.css` also ships `godmin-empty`, `godmin-form`, `godmin-table` and
140
161
  `godmin-table-scroll`. The last two go together: a table wider than a phone
141
162
  scrolls inside its own region rather than dragging the page sideways.
package/dist/base.css CHANGED
@@ -152,6 +152,43 @@ body {
152
152
  white-space: nowrap;
153
153
  }
154
154
 
155
+ .godmin-loading-screen {
156
+ padding: var(--wpds-dimension-padding-xl);
157
+ }
158
+
159
+ .godmin-loading-screen__ghost {
160
+ display: flex;
161
+ flex-direction: column;
162
+ gap: var(--wpds-dimension-gap-lg);
163
+ max-width: var(--wpds-dimension-surface-width-sm);
164
+ }
165
+
166
+ .godmin-loading-screen__title {
167
+ height: 32px;
168
+ width: 40%;
169
+ border-radius: var(--wpds-border-radius-sm);
170
+ }
171
+
172
+ .godmin-loading-screen__stroke {
173
+ height: 14px;
174
+ border-radius: var(--wpds-border-radius-sm);
175
+ }
176
+
177
+ .godmin-loading-screen__stroke:last-child {
178
+ width: 70%;
179
+ }
180
+
181
+ .godmin-loading-rows__ghost {
182
+ display: flex;
183
+ flex-direction: column;
184
+ gap: var(--wpds-dimension-gap-sm);
185
+ }
186
+
187
+ .godmin-loading-rows__row {
188
+ height: var(--wpds-dimension-size-lg);
189
+ border-radius: var(--wpds-border-radius-sm);
190
+ }
191
+
155
192
  /* Small viewport overrides live together at the end of the sheet, so they
156
193
  always win over the rules above them without extra specificity. */
157
194
  @media (max-width: 639px) {
package/dist/index.d.ts CHANGED
@@ -3,12 +3,14 @@ export type { AdminRootProps } from './admin-root.js';
3
3
  export { DENSE_BREAKPOINT, RAIL_BREAKPOINT, SMALL_VIEWPORT } from './breakpoints.js';
4
4
  export { Frame } from './frame.js';
5
5
  export type { CanvasMode, FrameCanvasProps, FrameRailProps, FrameRootProps, } from './frame.js';
6
+ export { LoadingRows, LoadingScreen } from './loading.js';
6
7
  export { NavScreen } from './nav-screen.js';
7
8
  export type { NavScreenProps } from './nav-screen.js';
8
9
  export { ErrorNotice, LoadMore, Page, PageTitle } from './page.js';
9
10
  export type { LoadMoreQuery, PageProps } from './page.js';
10
11
  export { Toaster, useToaster } from './toaster.js';
11
12
  export type { ToastAction, ToasterHandle, ToasterProps } from './toaster.js';
13
+ export { useLoadingGate } from './use-loading-gate.js';
12
14
  export { useMediaQuery } from './use-media-query.js';
13
15
  export { useTokenDocument } from './use-token-document.js';
14
16
  /**
package/dist/index.js CHANGED
@@ -2,9 +2,11 @@
2
2
  export { AdminRoot } from './admin-root.js';
3
3
  export { DENSE_BREAKPOINT, RAIL_BREAKPOINT, SMALL_VIEWPORT } from './breakpoints.js';
4
4
  export { Frame } from './frame.js';
5
+ export { LoadingRows, LoadingScreen } from './loading.js';
5
6
  export { NavScreen } from './nav-screen.js';
6
7
  export { ErrorNotice, LoadMore, Page, PageTitle } from './page.js';
7
8
  export { Toaster, useToaster } from './toaster.js';
9
+ export { useLoadingGate } from './use-loading-gate.js';
8
10
  export { useMediaQuery } from './use-media-query.js';
9
11
  export { useTokenDocument } from './use-token-document.js';
10
12
  /**
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Renders a content-shaped ghost while a screen's data loads.
3
+ * @param props - The label a screen reader announces.
4
+ * @returns The loading screen element.
5
+ */
6
+ export declare function LoadingScreen({ label }: {
7
+ label: string;
8
+ }): import("react").JSX.Element;
9
+ /**
10
+ * Renders a stack of row-shaped ghosts while a list's data loads.
11
+ * @param props - The label a screen reader announces and the row count.
12
+ * @returns The loading rows element.
13
+ */
14
+ export declare function LoadingRows({ label, rows }: {
15
+ label: string;
16
+ rows?: number;
17
+ }): import("react").JSX.Element;
@@ -0,0 +1,20 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { Skeleton, VisuallyHidden } from '@wordpress/ui';
4
+ const STROKES = 3;
5
+ /**
6
+ * Renders a content-shaped ghost while a screen's data loads.
7
+ * @param props - The label a screen reader announces.
8
+ * @returns The loading screen element.
9
+ */
10
+ export function LoadingScreen({ label }) {
11
+ return (_jsxs("div", { className: "godmin-loading-screen", children: [_jsx(VisuallyHidden, { role: "status", children: label }), _jsxs("div", { className: "godmin-loading-screen__ghost", "aria-hidden": "true", children: [_jsx(Skeleton, { className: "godmin-loading-screen__title" }), Array.from({ length: STROKES }, (_, stroke) => (_jsx(Skeleton, { className: "godmin-loading-screen__stroke" }, stroke)))] })] }));
12
+ }
13
+ /**
14
+ * Renders a stack of row-shaped ghosts while a list's data loads.
15
+ * @param props - The label a screen reader announces and the row count.
16
+ * @returns The loading rows element.
17
+ */
18
+ export function LoadingRows({ label, rows = 5 }) {
19
+ return (_jsxs("div", { className: "godmin-loading-rows", children: [_jsx(VisuallyHidden, { role: "status", children: label }), _jsx("div", { className: "godmin-loading-rows__ghost", "aria-hidden": "true", children: Array.from({ length: rows }, (_, row) => (_jsx(Skeleton, { className: "godmin-loading-rows__row" }, row))) })] }));
20
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Returns whether a loading ghost should stand in for the pending work.
3
+ * @param pending - Whether the work the ghost stands in for is still pending.
4
+ * @returns Whether to render the ghost.
5
+ */
6
+ export declare function useLoadingGate(pending: boolean): boolean;
@@ -0,0 +1,32 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { useEffect, useRef, useState } from 'react';
3
+ const SHOW_AFTER = 200;
4
+ const SHOW_FOR = 500;
5
+ /**
6
+ * Returns whether a loading ghost should stand in for the pending work.
7
+ * @param pending - Whether the work the ghost stands in for is still pending.
8
+ * @returns Whether to render the ghost.
9
+ */
10
+ export function useLoadingGate(pending) {
11
+ const [showing, setShowing] = useState(false);
12
+ const holdUntil = useRef(0);
13
+ useEffect(() => {
14
+ if (pending && !showing) {
15
+ const delay = setTimeout(() => {
16
+ holdUntil.current = Date.now() + SHOW_FOR;
17
+ setShowing(true);
18
+ }, SHOW_AFTER);
19
+ return () => clearTimeout(delay);
20
+ }
21
+ if (!pending && showing) {
22
+ const left = holdUntil.current - Date.now();
23
+ if (left <= 0) {
24
+ setShowing(false);
25
+ return;
26
+ }
27
+ const hold = setTimeout(() => setShowing(false), left);
28
+ return () => clearTimeout(hold);
29
+ }
30
+ }, [pending, showing]);
31
+ return showing;
32
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gopherium/godmin",
3
- "version": "0.2.2",
3
+ "version": "0.4.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",