@jfdevelops/react-layout 1.1.0 → 1.3.0

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

@@ -2,19 +2,22 @@ import { InvalidConfigError } from "../errors/invalid-config.mjs";
 import { MissingResourceProviderError } from "../errors/missing-resource-provider.mjs";
 import { LayoutConfigurationError } from "../errors/layout-configuration-error.mjs";
 import { ResourceModuleLoadError, ResourceRenderError } from "../errors/resource-state-error.mjs";
+import { capitalize } from "../utils/capitalize.mjs";
+import { StateComposableContext, createStateReferences, stateReferenceSource } from "./state-composable.mjs";
+import { mergeLayoutProps } from "./merge-layout-props.mjs";
+import { inspectDefinition, trackComposable } from "./inspection.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";
 import { createResourceConfig } from "./get-component.mjs";
 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 { StateComposableContext, createStateReferences } from "./state-composable.mjs";
 import { deferredRenderStateSymbol, definedResourceLayoutComponentSymbol, findDefinedRenderState, isDeferredRenderState, isLazyRenderState, lazyRenderStateSymbol } from "./render-state.mjs";
 import { LayoutComposablePresetProvider, collectComposablePresetEntries, makeComposable, resolveLayoutComposables } from "@jfdevelops/react-layout-composables";
 import { Component, Suspense, createContext, lazy, useCallback, useContext, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+import { inspectionId } from "@jfdevelops/react-layout-devtools-core";
 import { attachComponentPropDefinitions, createPrimitivePropBuilder, createProp, resolvePropDefinitionValues, validateProps } from "@jfdevelops/react-layout-validator";
 import { Fragment, jsx } from "react/jsx-runtime";
 
@@ -138,9 +141,21 @@ function assertUnreservedResourceSlugs(resources, owner) {
 		if (typeof resource !== "string") assertUnreservedResourceSlugs(resource.subResources, slug);
 	}
 }
-function defineResourceLayoutImpl(options, inheritedStateScope) {
+function defineResourceLayoutImpl(options, inheritedStateScope, inheritedInspection) {
 	const { options: inProps = {}, resources, layout, namespace: defaultNamespace = false } = options;
 	const shellId = options.shellId;
+	const inspection = inheritedInspection ? void 0 : inspectDefinition(resources);
+	if (inspection) inspection.store.node({
+		id: inspection.definition,
+		kind: "definition",
+		label: "Layout definition",
+		details: {
+			props: layout.props,
+			propSchemas: typeof inProps === "function" ? void 0 : inProps,
+			options: typeof inProps === "function" ? "Resource-specific schemas" : Object.keys(inProps),
+			states: typeof layout.render === "function" ? ["default"] : Object.keys(layout.render)
+		}
+	});
 	assertUnreservedResourceSlugs(resources);
 	const resourcesAccessor = createLayoutResourcesAccessor(resources);
 	const ResourceContext = createContext(void 0);
@@ -158,19 +173,70 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 	const normalizedResources = normalizeResources(resources);
 	const resourcesEnum = createPrimitivePropBuilder("string").enum(toResourceEnum(normalizedResources));
 	const definedResourceLayout = ((layoutOptions) => {
-		const { name, props: instancePropDefinitions, namespace = defaultNamespace, ...layoutOptionProps } = layoutOptions;
+		const { name: suppliedName, props: instancePropDefinitions, namespace = defaultNamespace, ...layoutOptionProps } = layoutOptions;
+		const naming = suppliedName ?? options.name;
+		const name = typeof naming === "function" ? naming({
+			resource: layoutOptions.resource,
+			states: typeof layout.render === "function" ? ["default"] : Object.keys(layout.render),
+			capitalize
+		}) : naming;
+		if (name !== void 0 && (typeof name !== "string" || !name)) throw new LayoutConfigurationError("A non-empty layout name is required");
 		const createComposableLayout = makeComposable();
 		const nameProp = createProp.string().literal(name);
+		const rawResolvedOptions = typeof inProps === "function" ? inProps({
+			resource: resourcesEnum,
+			name: nameProp
+		}) : inProps;
 		const { resolvedInProps, splitInProps } = splitLayoutInProps({
-			...typeof inProps === "function" ? inProps({
-				resource: resourcesEnum,
-				name: nameProp
-			}) : inProps,
+			...rawResolvedOptions,
 			...instancePropDefinitions,
 			...layoutOptionProps
 		});
 		const { composables, props: legacyLayoutProps } = layout;
 		const renderStates = typeof layout.render === "function" ? { default: layout.render } : layout.render;
+		const inspectionStore = inheritedInspection?.store ?? inspection.store;
+		const layoutId = inheritedInspection?.layout ?? inspectionStore.node({
+			id: inspectionId("layout"),
+			kind: "layout",
+			label: name ?? String(layoutOptionProps.resource),
+			details: {
+				resource: layoutOptionProps.resource,
+				props: legacyLayoutProps,
+				propSchemas: rawResolvedOptions
+			}
+		});
+		const resourceId = inheritedInspection?.resource ?? inspection?.resourceIds.get(String(layoutOptionProps.resource));
+		if (inspection) {
+			inspectionStore.edge(inspection.definition, layoutId, "defines");
+			if (resourceId) inspectionStore.edge(resourceId, layoutId, "renders");
+		}
+		const stateIds = new Map(Object.keys(renderStates).map((state) => [state, inheritedInspection?.state ?? inspectionStore.node({
+			id: inspectionId("state"),
+			kind: "state",
+			label: state,
+			unresolved: isLazyRenderState(renderStates[state]) || isDeferredRenderState(renderStates[state])
+		})]));
+		for (const id of stateIds.values()) inspectionStore.edge(layoutId, id, "defines");
+		const activeInspection = {
+			store: inspectionStore,
+			layout: layoutId,
+			resource: resourceId,
+			state: stateIds.get("default")
+		};
+		const referenceStateIds = /* @__PURE__ */ new Map();
+		function getReferenceStateId(input, label) {
+			let id = referenceStateIds.get(input);
+			if (!id) {
+				id = inspectionStore.node({
+					id: inspectionId("state-reference"),
+					kind: "state",
+					label,
+					details: { relationship: "Referenced render state" }
+				});
+				referenceStateIds.set(input, id);
+			}
+			return id;
+		}
 		const referenceComponents = /* @__PURE__ */ new Map();
 		const stateScope = inheritedStateScope ?? {
 			states: createStateReferences(renderStates),
@@ -178,7 +244,7 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 				for (const [stateName, input] of Object.entries(renderStates)) if (input === source.input) return stateName === "default" ? Component : stateComponents[stateName];
 				let reference = referenceComponents.get(source.input);
 				if (!reference) {
-					reference = createStateComponent(source.name, source.input, false);
+					reference = createStateComponent(source.name, source.input, false, source.fallbackStateName);
 					referenceComponents.set(source.input, reference);
 				}
 				return reference;
@@ -189,8 +255,18 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 		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;
+		if (!inheritedInspection) inspectionStore.node({
+			id: activeInspection.state,
+			kind: "state",
+			label: "default",
+			unresolved: createdDefaultState,
+			details: {
+				props: mergeLayoutProps(legacyLayoutProps, defaultState.props),
+				propSchemas: rawResolvedOptions
+			}
+		});
 		const render = defaultState.render;
-		const layoutProps = defaultState.props ?? legacyLayoutProps;
+		const layoutProps = mergeLayoutProps(legacyLayoutProps, defaultState.props);
 		const customLayoutProps = layoutProps?.custom;
 		const includeLayoutProps = layoutProps?.include;
 		const layoutOptionValues = layoutOptionProps;
@@ -208,7 +284,26 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			...composables?.(create, stateScope.states) ?? {},
 			...defaultState.composables?.(create, stateScope.states)
 		}) : void 0;
-		const resolvedComposables = defaultComposables ? resolveLayoutComposables(defaultComposables, layoutContext) : void 0;
+		const resolvedComposables = defaultComposables ? { ...resolveLayoutComposables(defaultComposables, layoutContext) } : void 0;
+		for (const [key, component] of Object.entries(resolvedComposables ?? {})) {
+			const id = inspectionStore.node({
+				id: inspectionId("composable"),
+				kind: "composable",
+				label: key,
+				details: {
+					displayName: component.displayName,
+					relationship: "declared; may not be rendered"
+				}
+			});
+			inspectionStore.edge(activeInspection.state, id, "declares");
+			resolvedComposables[key] = trackComposable(component, inspectionStore, id);
+			const reference = component[stateReferenceSource];
+			if (reference) {
+				const stateName = Object.entries(renderStates).find(([, input]) => input === reference.input)?.[0];
+				const target = stateName ? stateIds.get(stateName) : getReferenceStateId(reference.input, reference.name);
+				inspectionStore.edge(id, target, "references");
+			}
+		}
 		const mergedResolvedInProps = { ...resolvedInProps };
 		for (const { props: presetPropDefinitions } of collectComposablePresetEntries(resolvedComposables)) Object.assign(mergedResolvedInProps, presetPropDefinitions);
 		const composablePresetProps = Object.fromEntries(collectComposablePresetEntries(resolvedComposables).map(({ key, props: presetPropDefinitions }) => {
@@ -228,6 +323,10 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 		const stateComponents = {};
 		let CreatedDefaultStateComponent;
 		function RenderDefaultState({ renderProps }) {
+			useLayoutEffect(() => {
+				if (CreatedDefaultStateComponent) return;
+				return inspectionStore.mount(activeInspection.layout, activeInspection.state, ...resourceId ? [resourceId] : []);
+			}, []);
 			if (CreatedDefaultStateComponent) return /* @__PURE__ */ jsx(CreatedDefaultStateComponent, { ...renderProps });
 			return render(renderProps, mergedRenderContext);
 		}
@@ -271,7 +370,8 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 					children: /* @__PURE__ */ jsx(StateComposableContext.Provider, {
 						value: {
 							scope: stateScope,
-							props: layoutRenderProps
+							props: layoutRenderProps,
+							definitions: mergedResolvedInProps
 						},
 						children: /* @__PURE__ */ jsx(RenderDefaultState, { renderProps: layoutRenderProps })
 					})
@@ -293,24 +393,25 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			if (!compositionOptions.components) return {};
 			return { makeComposable: createComposableLayout(compositionOptions) };
 		}
-		function createStateComponent(stateName, input, validateStateName = true) {
+		function createStateComponent(stateName, input, validateStateName = true, fallbackStateName = stateName) {
+			const inspectedId = validateStateName ? stateIds.get(stateName) : getReferenceStateId(input, stateName);
 			if (isLazyRenderState(input)) {
 				const loadState = input[lazyRenderStateSymbol];
 				function createLazyState() {
 					return lazy(async () => {
-						const stateDefinition = findDefinedRenderState(await loadState().catch((error) => {
+						const stateDefinition = await findDefinedRenderState(await loadState().catch((error) => {
 							throw new ResourceModuleLoadError(String(layoutContext.resource), error);
 						}));
 						if (validateStateName && stateDefinition.state !== void 0 && stateDefinition.state !== stateName) throw new LayoutConfigurationError(`Lazy render state "${stateDefinition.state}" cannot be used as "${stateName}"`);
-						return { default: createLoadedStateComponent(validateStateName ? stateName : stateDefinition.state ?? stateName, stateDefinition) };
+						return { default: createLoadedStateComponent(validateStateName ? stateName : stateDefinition.state ?? stateName, stateDefinition, inspectedId) };
 					});
 				}
 				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;
+					const LoadingComponent = fallbackStateName === "Loading" ? void 0 : stateComponents.Loading;
+					const ErrorComponent = fallbackStateName === "Error" ? void 0 : stateComponents.Error;
 					function retry() {
 						LazyState.current = createLazyState();
 						rerender();
@@ -335,12 +436,12 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			}
 			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);
+			const StateComponent = createLoadedStateComponent(stateName, definition, inspectedId);
 			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 LoadingComponent = fallbackStateName === "Loading" ? void 0 : stateComponents.Loading;
+				const ErrorComponent = fallbackStateName === "Error" ? void 0 : stateComponents.Error;
 				const rendered = /* @__PURE__ */ jsx(Suspense, {
 					fallback: LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null,
 					children: /* @__PURE__ */ jsx(DeferredState, { ...props })
@@ -358,7 +459,17 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			}
 			return DeferredStateComponent;
 		}
-		function createLoadedStateComponent(stateName, definition) {
+		function createLoadedStateComponent(stateName, definition, inspectedState = stateIds.get(stateName)) {
+			if (inspectedState) inspectionStore.node({
+				id: inspectedState,
+				kind: "state",
+				label: stateName,
+				unresolved: false,
+				details: {
+					props: mergeLayoutProps(legacyLayoutProps, definition.props),
+					propSchemas: rawResolvedOptions
+				}
+			});
 			const stateComposables = composables || definition.composables ? (create) => ({
 				...composables?.(create, stateScope.states) ?? {},
 				...definition.composables?.(create, stateScope.states)
@@ -372,11 +483,15 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 				options: inProps,
 				layout: {
 					composables: stateComposables,
-					props: definition.props,
+					props: mergeLayoutProps(legacyLayoutProps, definition.props),
 					render: stateRender
 				}
-			}, stateScope).createResourceLayout({
+			}, stateScope, {
+				...activeInspection,
+				state: inspectedState ?? getReferenceStateId(definition, stateName)
+			}).createResourceLayout({
 				...layoutOptions,
+				name,
 				namespace: false
 			});
 			StateComponent.displayName = `${name}.${stateName}`;
@@ -408,7 +523,7 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			const definition = mergedResolvedInProps[key];
 			return [[key, isIncludedPropRequired(includeLayoutProps?.[key]) ? definition : definition.optional?.() ?? definition]];
 		}));
-		const rootComponent = attachComponentPropDefinitions(Object.assign(Component, {
+		const createdComponent = Object.assign(Component, {
 			displayName: name,
 			props: void 0,
 			resource: void 0,
@@ -418,7 +533,9 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 			}),
 			...stateComponents,
 			[definedResourceLayoutComponentSymbol]: true
-		}), {
+		});
+		inspectionStore.attach(createdComponent);
+		const rootComponent = attachComponentPropDefinitions(createdComponent, {
 			...customLayoutProps,
 			...includedComponentDefinitions
 		});
@@ -462,7 +579,7 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 		for (const { props: presetPropDefinitions } of collectComposablePresetEntries(resolvedComposables)) Object.assign(resolvedInProps, presetPropDefinitions);
 		return {
 			...resolvedInProps,
-			...(defaultState?.props ?? layout.props)?.custom
+			...mergeLayoutProps(layout.props, defaultState?.props)?.custom
 		};
 	}
 	const { createLayoutForResourceBuilder, forResource } = createForResource({
@@ -479,14 +596,16 @@ function defineResourceLayoutImpl(options, inheritedStateScope) {
 		})
 	};
 	if (layout.composables) createResourceLayoutExtras.makeComposable = createTopLevelMakeComposable();
-	return {
+	const createResourceLayout = Object.assign(definedResourceLayout, createResourceLayoutExtras);
+	const createResourceLinks = createResourceLinksFn(resources);
+	return (inspection?.store.attach ?? ((value) => value))({
 		createResourceConfig,
-		createResourceLayout: Object.assign(definedResourceLayout, createResourceLayoutExtras),
-		createResourceLinks: createResourceLinksFn(resources),
+		createResourceLayout,
+		createResourceLinks,
 		resources: resourcesAccessor,
 		ResourceProvider,
 		useResource
-	};
+	});
 }
 function defineResources(...resources) {
 	return resources;