shelving 1.262.0 → 1.262.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.262.0",
+	"version": "1.262.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/react/createAPIContext.d.ts

@@ -1,21 +1,20 @@
-import { type ReactElement, type ReactNode } from "react";
+import { type ReactElement } from "react";
 import type { Endpoint } from "../api/endpoint/Endpoint.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
+import type { ChildProps } from "../ui/index.js";
 import type { Nullish } from "../util/null.js";
 /**
- * Bundle of hooks and a provider component returned by `createAPIContext()`.
+ * Bundle of hooks and a provider component returned by `createAPIContext()`
  *
  * @see https://shelving.cc/react/APIContext
  */
 export interface APIContext<P, R> {
-    /** Get an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
+    /** React hook to return an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP): EndpointStore<PP, RR>;
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Nullish<Endpoint<PP, RR>>, payload: PP): EndpointStore<PP, RR> | undefined;
     /** The `<APIContext>` wrapper to give your React components access to this API provider. */
-    readonly APIContext: ({ children }: {
-        children: ReactNode;
-    }) => ReactElement;
+    readonly APIContext: (props: ChildProps) => ReactElement;
 }
 /**
  * Create an API context.
@@ -24,8 +23,6 @@ export interface APIContext<P, R> {
  *
  * @param provider `APIProvider` the created context resolves endpoint stores against.
  *
- * @todo Use and integreate our `EndpointCache` functionality and use it in this.
- *
  * @see https://shelving.cc/react/createAPIContext
  */
 export declare function createAPIContext<P, R>(provider: APIProvider<P, R>): APIContext<P, R>;

package/react/createAPIContext.js

@@ -11,8 +11,6 @@ import { useStore } from "./useStore.js";
  *
  * @param provider `APIProvider` the created context resolves endpoint stores against.
  *
- * @todo Use and integreate our `EndpointCache` functionality and use it in this.
- *
  * @see https://shelving.cc/react/createAPIContext
  */
 export function createAPIContext(provider) {

package/ui/inline/Code.module.css

@@ -19,9 +19,9 @@
 	.prose :is(code, kbd, samp, var):not(pre *) {
 		/* Box */
 		display: inline-block;
-		vertical-align: text-bottom;
 		padding-inline: var(--code-padding, var(--space-xxsmall));
 		border-radius: var(--code-radius, var(--radius-xxsmall));
+		vertical-align: baseline;
 
 		/* Style */
 		background: var(--code-background, var(--tint-90));

package/ui/inline/Mark.module.css

@@ -12,10 +12,10 @@
 		display: inline-block;
 		padding-inline: var(--mark-padding, var(--space-xxsmall));
 		border-radius: var(--mark-radius, var(--radius-xxsmall));
-		vertical-align: text-bottom;
+		vertical-align: baseline;
 
 		/* Style */
-		background-color: var(--mark-background, var(--tint-50));
+		background: var(--mark-background, var(--tint-80));
 		color: var(--mark-color, var(--tint-00));
 
 		/* Text */

package/ui/misc/Catcher.d.ts

@@ -22,9 +22,9 @@ export declare function RetryButton({ children, ...props }: RetryButtonProps): R
 /**
  * Props for a component that renders a caught error `reason`.
  *
- * @see https://shelving.cc/ui/ErrorComponentProps
+ * @see https://shelving.cc/ui/ErrorProps
  */
-export interface ErrorComponentProps {
+export interface ErrorProps {
     reason: unknown;
 }
 /**
@@ -34,7 +34,7 @@ export interface ErrorComponentProps {
  */
 export interface CatcherProps extends ChildProps {
     /** Component to render an error (defaults to `<ErrorNotice />`) */
-    as: (props: ErrorComponentProps) => ReactElement;
+    as: (props: ErrorProps) => ReactElement;
 }
 type CatcherState = {
     /** The error that was caught. */
@@ -56,27 +56,6 @@ export declare class Catcher extends Component<CatcherProps, CatcherState> {
     static getDerivedStateFromError(reason: unknown): CatcherState;
     render(): ReactNode;
 }
-/**
- * Props for `<PageCatcher>` — the page `children` to guard.
- *
- * @see https://shelving.cc/ui/PageCatcherProps
- */
-export interface PageCatcherProps extends ChildProps {
-}
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export declare function PageCatcher({ children }: PageCatcherProps): ReactElement;
-/**
- * Props for `<ErrorNotice>` — the caught error `reason`.
- *
- * @see https://shelving.cc/ui/ErrorNoticeProps
- */
-export interface ErrorNoticeProps extends ErrorComponentProps {
-}
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -85,14 +64,14 @@ export interface ErrorNoticeProps extends ErrorComponentProps {
  * @kind component
  * @see https://shelving.cc/ui/ErrorNotice
  */
-export declare function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement;
+export declare function ErrorNotice({ reason }: ErrorProps): ReactElement;
 /**
- * Props for `<ErrorPage>` — the caught error `reason`.
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
  *
- * @see https://shelving.cc/ui/ErrorPageProps
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
  */
-export interface ErrorPageProps extends ErrorComponentProps {
-}
+export declare function PageCatcher({ children }: ChildProps): ReactElement;
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
  *
@@ -101,5 +80,5 @@ export interface ErrorPageProps extends ErrorComponentProps {
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
-export declare function ErrorPage({ reason }: ErrorPageProps): ReactElement;
+export declare function ErrorPage({ reason }: ErrorProps): ReactElement;
 export {};

package/ui/misc/Catcher.js

@@ -3,6 +3,7 @@ import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { Component, createContext, use } from "react";
 import { getMessage } from "../../util/error.js";
 import { Card } from "../block/Card.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
 import { Button } from "../form/Button.js";
@@ -59,15 +60,6 @@ export class Catcher extends Component {
         return (_jsx(RetryContext, { value: retry, children: _jsx(ErrorComponent, { reason: reason }) }));
     }
 }
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export function PageCatcher({ children }) {
-    return _jsx(Catcher, { as: ErrorPage, children: children });
-}
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -78,7 +70,16 @@ export function PageCatcher({ children }) {
  */
 export function ErrorNotice({ reason }) {
     const message = getMessage(reason) ?? "Unknown error";
-    return (_jsxs(Notice, { status: "error", children: [_jsx("p", { children: message }), _jsx(RetryButton, { small: true })] }));
+    return (_jsxs(Notice, { status: "error", children: [_jsx(Paragraph, { children: message }), _jsx(RetryButton, { small: true })] }));
+}
+/**
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
+ */
+export function PageCatcher({ children }) {
+    return _jsx(Catcher, { as: ErrorPage, children: children });
 }
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.

package/ui/misc/Catcher.tsx

@@ -3,6 +3,7 @@ import { Component, createContext, type ReactElement, type ReactNode, use } from
 import { getMessage } from "../../util/error.js";
 import type { Callback } from "../../util/function.js";
 import { Card } from "../block/Card.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
 import { Button, type ButtonVariants } from "../form/Button.js";
@@ -51,9 +52,9 @@ export function RetryButton({ children = RETRY_CHILDREN, ...props }: RetryButton
 /**
  * Props for a component that renders a caught error `reason`.
  *
- * @see https://shelving.cc/ui/ErrorComponentProps
+ * @see https://shelving.cc/ui/ErrorProps
  */
-export interface ErrorComponentProps {
+export interface ErrorProps {
 	reason: unknown;
 }
 
@@ -64,7 +65,7 @@ export interface ErrorComponentProps {
  */
 export interface CatcherProps extends ChildProps {
 	/** Component to render an error (defaults to `<ErrorNotice />`) */
-	as: (props: ErrorComponentProps) => ReactElement;
+	as: (props: ErrorProps) => ReactElement;
 }
 
 type CatcherState = {
@@ -107,30 +108,6 @@ export class Catcher extends Component<CatcherProps, CatcherState> {
 	}
 }
 
-/**
- * Props for `<PageCatcher>` — the page `children` to guard.
- *
- * @see https://shelving.cc/ui/PageCatcherProps
- */
-export interface PageCatcherProps extends ChildProps {}
-
-/**
- * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
- *
- * @kind component
- * @see https://shelving.cc/ui/PageCatcher
- */
-export function PageCatcher({ children }: PageCatcherProps): ReactElement {
-	return <Catcher as={ErrorPage}>{children}</Catcher>;
-}
-
-/**
- * Props for `<ErrorNotice>` — the caught error `reason`.
- *
- * @see https://shelving.cc/ui/ErrorNoticeProps
- */
-export interface ErrorNoticeProps extends ErrorComponentProps {}
-
 /**
  * Render a caught error as an inline `<Notice>` with a retry button.
  *
@@ -139,22 +116,25 @@ export interface ErrorNoticeProps extends ErrorComponentProps {}
  * @kind component
  * @see https://shelving.cc/ui/ErrorNotice
  */
-export function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement {
+export function ErrorNotice({ reason }: ErrorProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (
 		<Notice status="error">
-			<p>{message}</p>
+			<Paragraph>{message}</Paragraph>
 			<RetryButton small />
 		</Notice>
 	);
 }
 
 /**
- * Props for `<ErrorPage>` — the caught error `reason`.
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
  *
- * @see https://shelving.cc/ui/ErrorPageProps
+ * @kind component
+ * @see https://shelving.cc/ui/PageCatcher
  */
-export interface ErrorPageProps extends ErrorComponentProps {}
+export function PageCatcher({ children }: ChildProps): ReactElement {
+	return <Catcher as={ErrorPage}>{children}</Catcher>;
+}
 
 /**
  * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
@@ -164,7 +144,7 @@ export interface ErrorPageProps extends ErrorComponentProps {}
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
-export function ErrorPage({ reason }: ErrorPageProps): ReactElement {
+export function ErrorPage({ reason }: ErrorProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (
 		<Page title="Error">

package/ui/misc/Loader.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `<Loader>` and `<PageLoader>` — the `children` to load plus an optional `fallback` shown while they suspend.
+ *
+ * @see https://shelving.cc/ui/LoaderProps
+ */
+export interface LoaderProps extends ChildProps {
+    /** Element rendered while `children` suspend (defaults to `LOADING`). */
+    readonly fallback?: ReactNode | undefined;
+}
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export declare function Loader({ children, fallback }: LoaderProps): ReactElement;
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export declare function PageLoader({ children, fallback }: LoaderProps): ReactElement;

package/ui/misc/Loader.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { CenteredLayout } from "../layout/CenteredLayout.js";
+import { Catcher, PageCatcher } from "./Catcher.js";
+import { LOADING } from "./Loading.js";
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export function Loader({ children, fallback = LOADING }) {
+    return (_jsx(Catcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
+}
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export function PageLoader({ children, fallback = _jsx(CenteredLayout, { children: LOADING }) }) {
+    return (_jsx(PageCatcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
+}

package/ui/misc/Loader.tsx

@@ -0,0 +1,49 @@
+import { type ReactElement, type ReactNode, Suspense } from "react";
+import { CenteredLayout } from "../layout/CenteredLayout.js";
+import type { ChildProps } from "../util/props.js";
+import { Catcher, PageCatcher } from "./Catcher.js";
+import { LOADING } from "./Loading.js";
+
+/**
+ * Props for `<Loader>` and `<PageLoader>` — the `children` to load plus an optional `fallback` shown while they suspend.
+ *
+ * @see https://shelving.cc/ui/LoaderProps
+ */
+export interface LoaderProps extends ChildProps {
+	/** Element rendered while `children` suspend (defaults to `LOADING`). */
+	readonly fallback?: ReactNode | undefined;
+}
+
+/**
+ * Load a component.
+ *
+ * - Wrapped in `<Catcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/Loader
+ */
+export function Loader({ children, fallback = LOADING }: LoaderProps): ReactElement {
+	return (
+		<Catcher>
+			<Suspense fallback={fallback}>{children}</Suspense>
+		</Catcher>
+	);
+}
+
+/**
+ * Load a page.
+ *
+ * - Wrapped in `<PageCatcher>` so child components can throw errors.
+ * - Wrapped in `<Suspense>` so child components can throw promises.
+ *
+ * @kind component
+ * @see https://shelving.cc/ui/PageLoader
+ */
+export function PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement {
+	return (
+		<PageCatcher>
+			<Suspense fallback={fallback}>{children}</Suspense>
+		</PageCatcher>
+	);
+}

package/ui/misc/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";

package/ui/misc/index.js

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";

package/ui/misc/index.tsx

@@ -1,5 +1,6 @@
 export * from "./Catcher.js";
 export * from "./Icon.js";
+export * from "./Loader.js";
 export * from "./Loading.js";
 export * from "./Mapper.js";
 export * from "./Markup.js";