shelving 1.262.0 → 1.263.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.262.0",
+	"version": "1.263.0",
 	"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/form/Button.md

@@ -60,6 +60,8 @@ import { getButtonClass } from "shelving/ui";
 | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
 | `--button-padding` | Inner padding | `var(--space-small)` (12px) |
 | `--button-small-padding` | Inner padding when `small` | `var(--space-xxsmall)` (4px) |
+| `--button-gap` | Gap between icon and label | `var(--space-small)` (12px) |
+| `--button-small-gap` | Gap between icon and label when `small` | `var(--space-xxsmall)` (4px) |
 | `--button-space` | Outer block margin | `var(--space-small)` (12px) |
 | `--button-font` | Font family | `var(--font-body)` |
 | `--button-weight` | Font weight | `var(--weight-strong)` (700) |

package/ui/form/Button.module.css

@@ -28,6 +28,7 @@
 		/* Content */
 		overflow: hidden;
 		word-break: normal;
+		gap: var(--button-gap, var(--space-small));
 		justify-content: center;
 		align-items: center;
 
@@ -61,6 +62,7 @@
 
 		/* Variants */
 		&.small {
+			gap: var(--button-small-gap, var(--space-xxsmall));
 			padding-block: var(--button-small-padding, var(--space-xxsmall));
 			padding-inline: var(--button-small-padding, var(--space-xxsmall));
 		}

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,21 +64,19 @@ 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.
- *
- * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
  *
  * @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

@@ -2,14 +2,11 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 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 { Row } from "../block/Row.js";
-import { Subheading } from "../block/Subheading.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Button } from "../form/Button.js";
 import { CenteredLayout } from "../layout/CenteredLayout.js";
 import { Notice } from "../notice/Notice.js";
 import { Page } from "../page/Page.js";
-import { Icon } from "./Icon.js";
 const RetryContext = createContext(undefined);
 RetryContext.displayName = "RetryContext";
 const RETRY_CHILDREN = (_jsxs(_Fragment, { children: [_jsx(ArrowPathIcon, {}), "Retry"] }));
@@ -59,15 +56,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,17 +66,23 @@ 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 })] }));
 }
 /**
- * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
  *
- * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown 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 a centered `<ErrorNotice>`.
  *
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
 export function ErrorPage({ reason }) {
-    const message = getMessage(reason) ?? "Unknown error";
-    return (_jsx(Page, { title: "Error", children: _jsx(CenteredLayout, { children: _jsxs(Card, { status: "error", children: [_jsx(Subheading, { children: _jsxs(Row, { left: true, children: [_jsx(Icon, { status: "error" }), " ", message] }) }), _jsx(RetryButton, {})] }) }) }));
+    return (_jsx(Page, { title: "Error", children: _jsx(CenteredLayout, { children: _jsx(ErrorNotice, { reason: reason }) }) }));
 }

package/ui/misc/Catcher.tsx

@@ -2,15 +2,12 @@ import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { Component, createContext, type ReactElement, type ReactNode, use } from "react";
 import { getMessage } from "../../util/error.js";
 import type { Callback } from "../../util/function.js";
-import { Card } from "../block/Card.js";
-import { Row } from "../block/Row.js";
-import { Subheading } from "../block/Subheading.js";
+import { Paragraph } from "../block/Paragraph.js";
 import { Button, type ButtonVariants } from "../form/Button.js";
 import { CenteredLayout } from "../layout/CenteredLayout.js";
 import { Notice } from "../notice/Notice.js";
 import { Page } from "../page/Page.js";
 import type { ChildProps, OptionalChildProps } from "../util/props.js";
-import { Icon } from "./Icon.js";
 
 const RetryContext = createContext<Callback | undefined>(undefined);
 RetryContext.displayName = "RetryContext";
@@ -51,9 +48,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 +61,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 +104,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,44 +112,37 @@ 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.
- *
- * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
  *
  * @kind component
  * @see https://shelving.cc/ui/ErrorPage
  */
-export function ErrorPage({ reason }: ErrorPageProps): ReactElement {
-	const message = getMessage(reason) ?? "Unknown error";
+export function ErrorPage({ reason }: ErrorProps): ReactElement {
 	return (
 		<Page title="Error">
 			<CenteredLayout>
-				<Card status="error">
-					<Subheading>
-						<Row left>
-							<Icon status="error" /> {message}
-						</Row>
-					</Subheading>
-					<RetryButton />
-				</Card>
+				<ErrorNotice reason={reason} />
 			</CenteredLayout>
 		</Page>
 	);

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";