@jfdevelops/react-layout 0.24.3 → 1.0.0

package/dist/create-config/define-layout.mjs

@@ -1,7 +1,8 @@
 import { InvalidConfigError } from "../errors/invalid-config.mjs";
 import { MissingResourceProviderError } from "../errors/missing-resource-provider.mjs";
 import { LayoutConfigurationError } from "../errors/layout-configuration-error.mjs";
-import { createIsValidResourceFn, normalizeResources, toResourceEnum } from "../resource.mjs";
+import { ResourceModuleLoadError, ResourceRenderError } from "../errors/resource-state-error.mjs";
+import { createIsValidResourceFn, normalizeResourceDefinitions, normalizeResources, toResourceEnum } from "../resource.mjs";
 import { functionalUpdate, pick } from "../utils.mjs";
 import { capitalize } from "../utils/capitalize.mjs";
 import { isResourceConfigComponentKey } from "./component-keys.mjs";
@@ -10,19 +11,48 @@ import { createResourceLinksFn } from "./create-resource-links.mjs";
 import { createForResource } from "./for-resource.mjs";
 import { createForResources } from "./for-resources/create-for-resources.mjs";
 import { ResourceLayoutShellPublisherContext, useResourceLayoutShellPublisher } from "./shell-context.mjs";
+import { deferredRenderStateSymbol, definedResourceLayoutComponentSymbol, findDefinedRenderState, isDeferredRenderState, isLazyRenderState, lazyRenderStateSymbol } from "./render-state.mjs";
 import { LayoutComposablePresetProvider, collectComposablePresetEntries, makeComposable, resolveLayoutComposables } from "@jfdevelops/react-layout-composables";
-import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { createPrimitivePropBuilder, createProp, resolvePropDefinitionValues, validateProps } from "@jfdevelops/react-layout-validator";
+import { Component, Suspense, createContext, lazy, useCallback, useContext, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+import { attachComponentPropDefinitions, createPrimitivePropBuilder, createProp, resolvePropDefinitionValues, validateProps } from "@jfdevelops/react-layout-validator";
 import { Fragment, jsx } from "react/jsx-runtime";
 
 //#region src/create-config/define-layout.tsx
+const RenderStateRetryContext = createContext(void 0);
+var RenderStateBoundary = class extends Component {
+	state = {};
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	retry = () => {
+		this.props.onRetry?.();
+		this.setState({ error: void 0 });
+	};
+	render() {
+		if (this.state.error !== void 0) return this.props.fallback(this.state.error, this.retry);
+		return this.props.children;
+	}
+};
+function toResourceStateError(resource, state, error) {
+	return error instanceof ResourceModuleLoadError || error instanceof ResourceRenderError ? error : new ResourceRenderError(resource, state, error);
+}
 function createResourceSelection(definitions) {
 	const selection = (() => definitions);
 	selection.isResource = createIsValidResourceFn(definitions);
 	return selection;
 }
+/**
+* Creates the callable resource accessor shared by global and bound layout
+* definitions.
+*
+* @param resources - Resource definitions to expose and normalize.
+* @returns A callable normalized accessor with raw, selection, and guard APIs.
+* @internal
+*/
 function createLayoutResourcesAccessor(resources) {
-	const accessor = (() => resources);
+	const normalizedResources = normalizeResourceDefinitions(resources);
+	const accessor = ((select) => select ? select(normalizedResources) : normalizedResources);
+	accessor.raw = ((select) => select ? select(resources) : resources);
 	accessor.isResource = createIsValidResourceFn(resources);
 	accessor.omit = ((...keys) => createResourceSelection(resources.filter((resource) => !keys.includes(readResourceSlug(resource)))));
 	accessor.pick = ((...keys) => createResourceSelection(resources.filter((resource) => keys.includes(readResourceSlug(resource)))));
@@ -88,6 +118,15 @@ function resolveLayoutOptionDefaults(defaults, options) {
 	else resolved[key] = functionalUpdate(defaultValue, options[key]);
 	return resolved;
 }
+function getSynchronousRenderStateDefinition(input, fallbackProps) {
+	if (isLazyRenderState(input)) return;
+	if (isDeferredRenderState(input)) return input[deferredRenderStateSymbol];
+	if (typeof input === "function") return {
+		props: fallbackProps,
+		render: input
+	};
+	return typeof input === "object" && input !== null ? input : void 0;
+}
 function readResourceSlug(resource) {
 	return typeof resource === "string" ? resource : resource.value;
 }
@@ -129,7 +168,15 @@ function defineResourceLayoutImpl(options) {
 			...instancePropDefinitions,
 			...layoutOptionProps
 		});
-		const { composables, render, props: layoutProps } = layout;
+		const { composables, props: legacyLayoutProps } = layout;
+		const renderStates = typeof layout.render === "function" ? { default: layout.render } : layout.render;
+		const defaultRenderInput = renderStates.default;
+		const createdDefaultState = isDeferredRenderState(defaultRenderInput) || isLazyRenderState(defaultRenderInput);
+		const defaultRenderDefinition = getSynchronousRenderStateDefinition(defaultRenderInput, legacyLayoutProps) ?? { render: () => null };
+		if (typeof defaultRenderDefinition !== "object" || defaultRenderDefinition === null || !("render" in defaultRenderDefinition) || typeof defaultRenderDefinition.render !== "function") throw new LayoutConfigurationError("The \"default\" render state must define a render function");
+		const defaultState = defaultRenderDefinition;
+		const render = defaultState.render;
+		const layoutProps = defaultState.props ?? legacyLayoutProps;
 		const customLayoutProps = layoutProps?.custom;
 		const includeLayoutProps = layoutProps?.include;
 		const layoutOptionValues = layoutOptionProps;
@@ -143,7 +190,11 @@ function defineResourceLayoutImpl(options) {
 			layoutName: name,
 			resource: layoutContext.resource
 		};
-		const resolvedComposables = composables ? resolveLayoutComposables(composables, layoutContext) : void 0;
+		const defaultComposables = defaultState.composables ? (create) => ({
+			...composables?.(create) ?? {},
+			...defaultState.composables?.(create)
+		}) : composables;
+		const resolvedComposables = defaultComposables ? resolveLayoutComposables(defaultComposables, layoutContext) : void 0;
 		const mergedResolvedInProps = { ...resolvedInProps };
 		for (const { props: presetPropDefinitions } of collectComposablePresetEntries(resolvedComposables)) Object.assign(mergedResolvedInProps, presetPropDefinitions);
 		const composablePresetProps = Object.fromEntries(collectComposablePresetEntries(resolvedComposables).map(({ key, props: presetPropDefinitions }) => {
@@ -160,6 +211,12 @@ function defineResourceLayoutImpl(options) {
 			name: layoutContext.name,
 			inProps: splitInProps
 		};
+		const stateComponents = {};
+		let CreatedDefaultStateComponent;
+		function RenderDefaultState({ renderProps }) {
+			if (CreatedDefaultStateComponent) return /* @__PURE__ */ jsx(CreatedDefaultStateComponent, { ...renderProps });
+			return render(renderProps, mergedRenderContext);
+		}
 		function Component(props) {
 			const publishResource = useResourceLayoutShellPublisher();
 			useLayoutEffect(() => {
@@ -193,26 +250,153 @@ function defineResourceLayoutImpl(options) {
 				...validatedProps,
 				...layoutRenderIncludedProps
 			};
-			return /* @__PURE__ */ jsx(ResourceProvider, {
+			const rendered = /* @__PURE__ */ jsx(ResourceProvider, {
 				resource: layoutContext.resource,
 				children: /* @__PURE__ */ jsx(LayoutComposablePresetProvider, {
 					value: composablePresetProps,
-					children: render(layoutRenderProps, mergedRenderContext)
+					children: /* @__PURE__ */ jsx(RenderDefaultState, { renderProps: layoutRenderProps })
 				})
 			});
+			const ErrorComponent = stateComponents.Error;
+			return ErrorComponent ? /* @__PURE__ */ jsx(RenderStateBoundary, {
+				fallback: (error, retry) => /* @__PURE__ */ jsx(RenderStateRetryContext.Provider, {
+					value: retry,
+					children: /* @__PURE__ */ jsx(ErrorComponent, {
+						error: toResourceStateError(String(layoutContext.resource), "default", error),
+						retry
+					})
+				}),
+				children: rendered
+			}) : rendered;
 		}
 		function createComposition(compositionOptions) {
 			if (!compositionOptions.components) return {};
 			return { makeComposable: createComposableLayout(compositionOptions) };
 		}
-		return Object.assign(Component, {
+		function createStateComponent(stateName, input) {
+			if (isLazyRenderState(input)) {
+				const loadState = input[lazyRenderStateSymbol];
+				function createLazyState() {
+					return lazy(async () => {
+						const stateDefinition = findDefinedRenderState(await loadState().catch((error) => {
+							throw new ResourceModuleLoadError(String(layoutContext.resource), error);
+						}));
+						if (stateDefinition.state !== void 0 && stateDefinition.state !== stateName) throw new LayoutConfigurationError(`Lazy render state "${stateDefinition.state}" cannot be used as "${stateName}"`);
+						return { default: createLoadedStateComponent(stateName, stateDefinition) };
+					});
+				}
+				function LazyStateComponent(props) {
+					const [, rerender] = useReducer((version) => version + 1, 0);
+					const LazyState = useRef(createLazyState());
+					const CurrentLazyState = LazyState.current;
+					const LoadingComponent = stateName === "Loading" ? void 0 : stateComponents.Loading;
+					const ErrorComponent = stateName === "Error" ? void 0 : stateComponents.Error;
+					function retry() {
+						LazyState.current = createLazyState();
+						rerender();
+					}
+					const rendered = /* @__PURE__ */ jsx(Suspense, {
+						fallback: LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null,
+						children: /* @__PURE__ */ jsx(CurrentLazyState, { ...props })
+					});
+					return ErrorComponent ? /* @__PURE__ */ jsx(RenderStateBoundary, {
+						fallback: (error, reset) => /* @__PURE__ */ jsx(RenderStateRetryContext.Provider, {
+							value: reset,
+							children: /* @__PURE__ */ jsx(ErrorComponent, {
+								error: toResourceStateError(String(layoutContext.resource), stateName, error),
+								retry: reset
+							})
+						}),
+						onRetry: retry,
+						children: rendered
+					}) : rendered;
+				}
+				return LazyStateComponent;
+			}
+			const definition = isDeferredRenderState(input) ? input[deferredRenderStateSymbol] : typeof input === "function" ? { render: input } : input;
+			if (typeof definition !== "object" || definition === null || !("render" in definition) || typeof definition.render !== "function") throw new LayoutConfigurationError(`Render state "${stateName}" must define a render function`);
+			const StateComponent = createLoadedStateComponent(stateName, definition);
+			if (!isDeferredRenderState(input)) return StateComponent;
+			const DeferredState = lazy(() => Promise.resolve({ default: StateComponent }));
+			function DeferredStateComponent(props) {
+				const LoadingComponent = stateName === "Loading" ? void 0 : stateComponents.Loading;
+				const ErrorComponent = stateName === "Error" ? void 0 : stateComponents.Error;
+				const rendered = /* @__PURE__ */ jsx(Suspense, {
+					fallback: LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null,
+					children: /* @__PURE__ */ jsx(DeferredState, { ...props })
+				});
+				return ErrorComponent ? /* @__PURE__ */ jsx(RenderStateBoundary, {
+					fallback: (error, retry) => /* @__PURE__ */ jsx(RenderStateRetryContext.Provider, {
+						value: retry,
+						children: /* @__PURE__ */ jsx(ErrorComponent, {
+							error: toResourceStateError(String(layoutContext.resource), stateName, error),
+							retry
+						})
+					}),
+					children: rendered
+				}) : rendered;
+			}
+			return DeferredStateComponent;
+		}
+		function createLoadedStateComponent(stateName, definition) {
+			const stateComposables = definition.composables ? (create) => ({
+				...composables?.(create) ?? {},
+				...definition.composables?.(create)
+			}) : composables;
+			const stateRender = stateName === "Error" ? (props, context) => /* @__PURE__ */ jsx(RenderStateRetryContext.Consumer, { children: (retry) => definition.render(props, {
+				...context,
+				retry
+			}) }) : definition.render;
+			const StateComponent = defineResourceLayoutImpl({
+				resources,
+				options: inProps,
+				layout: {
+					composables: stateComposables,
+					props: definition.props,
+					render: stateRender
+				}
+			}).createResourceLayout(layoutOptions);
+			StateComponent.displayName = `${name}.${stateName}`;
+			return StateComponent;
+		}
+		if (createdDefaultState) CreatedDefaultStateComponent = createStateComponent("default", defaultRenderInput);
+		for (const [stateName, input] of Object.entries(renderStates)) {
+			if (stateName === "default") continue;
+			if ([
+				"__proto__",
+				"apply",
+				"arguments",
+				"bind",
+				"call",
+				"caller",
+				"displayName",
+				"length",
+				"makeComposable",
+				"name",
+				"props",
+				"prototype",
+				"resource"
+			].includes(stateName)) throw new LayoutConfigurationError(`Render state name "${stateName}" is reserved`);
+			stateComponents[stateName] = createStateComponent(stateName, input);
+		}
+		const includedComponentDefinitions = Object.fromEntries(Object.keys(includeLayoutProps ?? {}).flatMap((key) => {
+			if (!allowsComponentPassthrough(includeLayoutProps?.[key]) || !(key in mergedResolvedInProps)) return [];
+			const definition = mergedResolvedInProps[key];
+			return [[key, isIncludedPropRequired(includeLayoutProps?.[key]) ? definition : definition.optional?.() ?? definition]];
+		}));
+		return attachComponentPropDefinitions(Object.assign(Component, {
 			displayName: name,
 			props: void 0,
 			resource: void 0,
 			...createComposition({
 				components: resolvedComposables,
 				name
-			})
+			}),
+			...stateComponents,
+			[definedResourceLayoutComponentSymbol]: true
+		}), {
+			...customLayoutProps,
+			...includedComponentDefinitions
 		});
 	});
 	const createTopLevelMakeComposable = () => {
@@ -228,7 +412,12 @@ function defineResourceLayoutImpl(options) {
 			resource: resourcesEnum,
 			name: createProp.string().literal(componentName)
 		}) : inProps);
-		const resolvedComposables = layout.composables ? resolveLayoutComposables(layout.composables, {
+		const defaultState = getSynchronousRenderStateDefinition((typeof layout.render === "function" ? { default: layout.render } : layout.render).default, layout.props);
+		const defaultComposables = defaultState?.composables ? (create) => ({
+			...layout.composables?.(create) ?? {},
+			...defaultState.composables?.(create)
+		}) : layout.composables;
+		const resolvedComposables = defaultComposables ? resolveLayoutComposables(defaultComposables, {
 			resource,
 			name: componentName,
 			capitalize
@@ -236,7 +425,7 @@ function defineResourceLayoutImpl(options) {
 		for (const { props: presetPropDefinitions } of collectComposablePresetEntries(resolvedComposables)) Object.assign(resolvedInProps, presetPropDefinitions);
 		return {
 			...resolvedInProps,
-			...layout.props?.custom
+			...(defaultState?.props ?? layout.props)?.custom
 		};
 	}
 	const { createLayoutForResourceBuilder, forResource } = createForResource({
@@ -445,5 +634,5 @@ const defineResourceLayout = Object.assign(defineResourceLayoutImpl, {
 });
 
 //#endregion
-export { defineResourceLayout };
+export { createLayoutResourcesAccessor, defineResourceLayout };
 //# sourceMappingURL=define-layout.mjs.map