@pisell/materials 6.12.39 → 6.12.41

package/es/components/PisellSelectionFlow/PisellSelectionFlow.d.ts

@@ -0,0 +1,7 @@
+import { PisellSelectionFlowProps, SelectionFlowRef } from "./types.js";
+import React from "react";
+
+//#region src/components/PisellSelectionFlow/PisellSelectionFlow.d.ts
+declare const _default: <TDraft, TDraftUpdate, TField extends string, TModuleType extends string, TServices = unknown, THostContext = unknown>(props: PisellSelectionFlowProps<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext> & React.RefAttributes<SelectionFlowRef<TDraft, TDraftUpdate, TField, TModuleType>>) => React.ReactElement | null;
+//#endregion
+export { _default };

package/es/components/PisellSelectionFlow/PisellSelectionFlow.js

@@ -0,0 +1,392 @@
+import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
+import { SelectionFlowCompileError } from "./types.js";
+import { compileSelectionFlowSteps } from "./compiler.js";
+import { SelectionFlowProvider } from "./context.js";
+import { useFlowDraft } from "./hooks/useFlowDraft.js";
+import { getCompiledStepsFingerprint, getSelectionFlowErrorMessage } from "./utils.js";
+import { useFlowModuleLifecycle } from "./hooks/useFlowModuleLifecycle.js";
+import { useFlowNavigation } from "./hooks/useFlowNavigation.js";
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+//#region src/components/PisellSelectionFlow/PisellSelectionFlow.tsx
+const createUnexpectedCompileError = (error) => {
+	return new SelectionFlowCompileError([{
+		code: "APPLICABILITY_CHECK_FAILED",
+		message: `Selection flow compilation failed: ${getSelectionFlowErrorMessage(error)}`
+	}]);
+};
+const SelectionFlow = ({ registry, draftAdapter, steps, initialDraft, initialStepIndex = 0, hostContext, services, children, onDraftChange, onStepChange, onCompiledStepsChange, onValidationFailed, onConfigurationError, onComplete }, ref) => {
+	const mountedRef = useRef(true);
+	const flowGenerationRef = useRef(0);
+	const draftRevisionRef = useRef(0);
+	const navigationRevisionRef = useRef(0);
+	const transitionPendingRef = useRef(false);
+	const processDraftChangeRef = useRef(() => void 0);
+	const onDraftChangeRef = useRef(onDraftChange);
+	onDraftChangeRef.current = onDraftChange;
+	const onCompleteRef = useRef(onComplete);
+	onCompleteRef.current = onComplete;
+	const { draft, draftRef, updateDraft } = useFlowDraft({
+		initialDraft,
+		draftAdapter,
+		mountedRef,
+		draftRevisionRef,
+		onDraftChangeRef,
+		processDraftChangeRef
+	});
+	const initialDraftRef = useRef(initialDraft);
+	const [moduleState, setModuleStateMap] = useState({});
+	const moduleStateRef = useRef(moduleState);
+	moduleStateRef.current = moduleState;
+	const [moduleData, setModuleDataMap] = useState({});
+	const moduleDataRef = useRef(moduleData);
+	moduleDataRef.current = moduleData;
+	const [currentStepIndex, setCurrentStepIndex] = useState(() => Math.max(0, initialStepIndex));
+	const currentStepIndexRef = useRef(currentStepIndex);
+	currentStepIndexRef.current = currentStepIndex;
+	const currentStepKeyRef = useRef();
+	const [isCompleting, setIsCompleting] = useState(false);
+	const isCompletingRef = useRef(isCompleting);
+	isCompletingRef.current = isCompleting;
+	const [completionError, setCompletionError] = useState();
+	const [completionReason, setCompletionReason] = useState();
+	const completedRef = useRef(false);
+	const completionPromiseRef = useRef(null);
+	const validatedCompletionRef = useRef(null);
+	const moduleHandlesRef = useRef(/* @__PURE__ */ new Map());
+	const activeModuleKeysRef = useRef(/* @__PURE__ */ new Set());
+	const moduleRevisionRef = useRef(/* @__PURE__ */ new Map());
+	const moduleInitializationRef = useRef(/* @__PURE__ */ new Map());
+	const moduleDependencyLifecycleRef = useRef(/* @__PURE__ */ new Map());
+	const pendingModuleChangeRef = useRef(/* @__PURE__ */ new Map());
+	const compiledStepsRef = useRef([]);
+	const configurationErrorRef = useRef(null);
+	const contextRef = useRef(null);
+	const notifiedStepRef = useRef();
+	const notifiedCompiledStepsRef = useRef();
+	const createRuntimeIssue = useCallback((code, params) => ({
+		code,
+		params
+	}), []);
+	useEffect(() => {
+		const generation = flowGenerationRef.current + 1;
+		flowGenerationRef.current = generation;
+		mountedRef.current = true;
+		if (generation > 1) {
+			const nextModuleState = Object.fromEntries(Object.keys(moduleStateRef.current).map((moduleKey) => [moduleKey, { status: "idle" }]));
+			moduleStateRef.current = nextModuleState;
+			moduleDataRef.current = {};
+			setModuleStateMap(nextModuleState);
+			setModuleDataMap({});
+		}
+		return () => {
+			mountedRef.current = false;
+			if (flowGenerationRef.current === generation) flowGenerationRef.current += 1;
+			navigationRevisionRef.current += 1;
+			moduleInitializationRef.current.clear();
+			moduleDependencyLifecycleRef.current.clear();
+			pendingModuleChangeRef.current.clear();
+			moduleHandlesRef.current.clear();
+		};
+	}, []);
+	const commitModuleState = useCallback((moduleKey, nextState) => {
+		if (!mountedRef.current) return;
+		const previous = moduleStateRef.current[moduleKey];
+		if ((previous === null || previous === void 0 ? void 0 : previous.status) === nextState.status && (previous === null || previous === void 0 ? void 0 : previous.message) === nextState.message && (previous === null || previous === void 0 ? void 0 : previous.reason) === nextState.reason && (previous === null || previous === void 0 ? void 0 : previous.error) === nextState.error) return;
+		const nextMap = _objectSpread2(_objectSpread2({}, moduleStateRef.current), {}, { [moduleKey]: nextState });
+		moduleStateRef.current = nextMap;
+		setModuleStateMap(nextMap);
+	}, []);
+	const setModuleStatus = useCallback((moduleKey, status, message, error) => {
+		commitModuleState(moduleKey, {
+			status,
+			message,
+			error
+		});
+	}, [commitModuleState]);
+	const setModuleData = useCallback((moduleKey, value) => {
+		if (!mountedRef.current) return;
+		const nextMap = _objectSpread2(_objectSpread2({}, moduleDataRef.current), {}, { [moduleKey]: value });
+		moduleDataRef.current = nextMap;
+		setModuleDataMap(nextMap);
+	}, []);
+	const clearModuleData = useCallback((moduleKey) => {
+		if (!mountedRef.current) return;
+		if (!(moduleKey in moduleDataRef.current)) return;
+		const nextMap = _objectSpread2({}, moduleDataRef.current);
+		delete nextMap[moduleKey];
+		moduleDataRef.current = nextMap;
+		setModuleDataMap(nextMap);
+	}, []);
+	const provisionalContext = useMemo(() => ({
+		draft,
+		updateDraft,
+		moduleState,
+		setModuleState: commitModuleState,
+		setModuleStatus,
+		moduleData,
+		getModuleData: (moduleKey) => moduleDataRef.current[moduleKey],
+		setModuleData,
+		clearModuleData,
+		steps: [],
+		currentStepIndex,
+		currentStep: void 0,
+		hostContext,
+		services
+	}), [
+		hostContext,
+		clearModuleData,
+		commitModuleState,
+		currentStepIndex,
+		draft,
+		moduleData,
+		moduleState,
+		services,
+		setModuleData,
+		setModuleStatus,
+		updateDraft
+	]);
+	const compilation = useMemo(() => {
+		try {
+			return {
+				steps: compileSelectionFlowSteps(steps, provisionalContext, initialDraftRef.current, registry, draftAdapter),
+				error: null
+			};
+		} catch (error) {
+			return {
+				steps: [],
+				error: error instanceof SelectionFlowCompileError ? error : createUnexpectedCompileError(error)
+			};
+		}
+	}, [
+		draft,
+		draftAdapter,
+		hostContext,
+		registry,
+		services,
+		steps
+	]);
+	const compiledSteps = compilation.steps;
+	const configurationError = compilation.error;
+	compiledStepsRef.current = compiledSteps;
+	configurationErrorRef.current = configurationError;
+	let resolvedCurrentStepIndex = Math.min(Math.max(0, currentStepIndex), Math.max(0, compiledSteps.length - 1));
+	if (currentStepKeyRef.current) {
+		const trackedIndex = compiledSteps.findIndex((step) => step.key === currentStepKeyRef.current);
+		if (trackedIndex >= 0) resolvedCurrentStepIndex = trackedIndex;
+		else if (compiledSteps.length > 0) {
+			const firstReviewIndex = compiledSteps.findIndex((step) => step.modules.some((module) => {
+				var _moduleStateRef$curre;
+				return ((_moduleStateRef$curre = moduleStateRef.current[module.key]) === null || _moduleStateRef$curre === void 0 ? void 0 : _moduleStateRef$curre.status) !== "ready";
+			}));
+			resolvedCurrentStepIndex = firstReviewIndex >= 0 ? firstReviewIndex : resolvedCurrentStepIndex;
+		}
+	}
+	const currentStep = compiledSteps[resolvedCurrentStepIndex];
+	currentStepIndexRef.current = resolvedCurrentStepIndex;
+	currentStepKeyRef.current = currentStep === null || currentStep === void 0 ? void 0 : currentStep.key;
+	const contextValue = useMemo(() => _objectSpread2(_objectSpread2({}, provisionalContext), {}, {
+		steps: compiledSteps,
+		currentStepIndex: resolvedCurrentStepIndex,
+		currentStep
+	}), [
+		compiledSteps,
+		currentStep,
+		provisionalContext,
+		resolvedCurrentStepIndex
+	]);
+	contextRef.current = contextValue;
+	const getFreshContext = useCallback(() => {
+		const current = contextRef.current;
+		if (!mountedRef.current || !current) return null;
+		return _objectSpread2(_objectSpread2({}, current), {}, {
+			draft: draftRef.current,
+			moduleState: moduleStateRef.current,
+			moduleData: moduleDataRef.current
+		});
+	}, []);
+	useEffect(() => {
+		if (!configurationError) return;
+		onConfigurationError === null || onConfigurationError === void 0 || onConfigurationError(configurationError);
+	}, [configurationError, onConfigurationError]);
+	useEffect(() => {
+		if (configurationError) return;
+		const fingerprint = getCompiledStepsFingerprint(compiledSteps);
+		if (notifiedCompiledStepsRef.current === fingerprint) return;
+		notifiedCompiledStepsRef.current = fingerprint;
+		onCompiledStepsChange === null || onCompiledStepsChange === void 0 || onCompiledStepsChange(compiledSteps);
+	}, [
+		compiledSteps,
+		configurationError,
+		onCompiledStepsChange
+	]);
+	useEffect(() => {
+		if (currentStepIndex === resolvedCurrentStepIndex) return;
+		setCurrentStepIndex(resolvedCurrentStepIndex);
+	}, [currentStepIndex, resolvedCurrentStepIndex]);
+	useEffect(() => {
+		if (!currentStep) return;
+		const notificationKey = `${resolvedCurrentStepIndex}:${currentStep.key}`;
+		if (notifiedStepRef.current === notificationKey) return;
+		notifiedStepRef.current = notificationKey;
+		onStepChange === null || onStepChange === void 0 || onStepChange(resolvedCurrentStepIndex, currentStep);
+	}, [
+		currentStep,
+		onStepChange,
+		resolvedCurrentStepIndex
+	]);
+	useEffect(() => {
+		const nextMap = _objectSpread2({}, moduleStateRef.current);
+		const nextDataMap = _objectSpread2({}, moduleDataRef.current);
+		const nextActiveKeys = /* @__PURE__ */ new Set();
+		let changed = false;
+		let dataChanged = false;
+		for (const step of compiledSteps) for (const module of step.modules) {
+			nextActiveKeys.add(module.key);
+			if (!nextMap[module.key]) {
+				nextMap[module.key] = { status: "idle" };
+				changed = true;
+			}
+		}
+		activeModuleKeysRef.current.forEach((moduleKey) => {
+			if (nextActiveKeys.has(moduleKey)) return;
+			moduleRevisionRef.current.set(moduleKey, (moduleRevisionRef.current.get(moduleKey) || 0) + 1);
+			moduleInitializationRef.current.delete(moduleKey);
+			moduleDependencyLifecycleRef.current.delete(moduleKey);
+			pendingModuleChangeRef.current.delete(moduleKey);
+			moduleHandlesRef.current.delete(moduleKey);
+			if (moduleKey in nextMap) {
+				delete nextMap[moduleKey];
+				changed = true;
+			}
+			if (moduleKey in nextDataMap) {
+				delete nextDataMap[moduleKey];
+				dataChanged = true;
+			}
+		});
+		activeModuleKeysRef.current = nextActiveKeys;
+		if (changed) {
+			moduleStateRef.current = nextMap;
+			setModuleStateMap(nextMap);
+		}
+		if (dataChanged) {
+			moduleDataRef.current = nextDataMap;
+			setModuleDataMap(nextDataMap);
+		}
+	}, [compiledSteps]);
+	const { ensureModuleReady } = useFlowModuleLifecycle({
+		registry,
+		draftAdapter,
+		createRuntimeIssue,
+		mountedRef,
+		flowGenerationRef,
+		draftRevisionRef,
+		draftRef,
+		moduleRevisionRef,
+		moduleInitializationRef,
+		moduleDependencyLifecycleRef,
+		pendingModuleChangeRef,
+		compiledStepsRef,
+		moduleStateRef,
+		processDraftChangeRef,
+		commitModuleState,
+		getFreshContext,
+		currentStep,
+		configurationError,
+		compiledSteps,
+		resolvedCurrentStepIndex,
+		draft,
+		moduleState
+	});
+	const { validateCurrentStep, complete, next, back } = useFlowNavigation({
+		registry,
+		draftAdapter,
+		createRuntimeIssue,
+		mountedRef,
+		moduleStateRef,
+		moduleRevisionRef,
+		draftRevisionRef,
+		flowGenerationRef,
+		moduleHandlesRef,
+		configurationErrorRef,
+		compiledStepsRef,
+		currentStepIndexRef,
+		currentStepKeyRef,
+		validatedCompletionRef,
+		navigationRevisionRef,
+		transitionPendingRef,
+		completedRef,
+		completionPromiseRef,
+		isCompletingRef,
+		draftRef,
+		onCompleteRef,
+		ensureModuleReady,
+		commitModuleState,
+		getFreshContext,
+		onValidationFailed,
+		setCurrentStepIndex,
+		setCompletionError,
+		setCompletionReason,
+		setIsCompleting
+	});
+	const getState = useCallback(() => {
+		const stepIndex = currentStepIndexRef.current;
+		return {
+			draft: draftRef.current,
+			currentStepIndex: stepIndex,
+			currentStep: compiledStepsRef.current[stepIndex],
+			steps: compiledStepsRef.current,
+			moduleState: moduleStateRef.current,
+			moduleData: moduleDataRef.current,
+			isCompleting: isCompletingRef.current,
+			isCompleted: completedRef.current,
+			configurationError: configurationErrorRef.current
+		};
+	}, []);
+	useImperativeHandle(ref, () => ({
+		next,
+		back,
+		updateDraft,
+		validateCurrentStep,
+		complete,
+		getState
+	}), [
+		back,
+		complete,
+		getState,
+		next,
+		updateDraft,
+		validateCurrentStep
+	]);
+	const registerModuleHandle = useCallback((moduleKey, handle) => {
+		if (handle) moduleHandlesRef.current.set(moduleKey, handle);
+		else moduleHandlesRef.current.delete(moduleKey);
+	}, []);
+	const getModuleHandle = useCallback((moduleKey) => moduleHandlesRef.current.get(moduleKey), []);
+	const controller = {
+		draft,
+		currentStepIndex: resolvedCurrentStepIndex,
+		currentStep,
+		steps: compiledSteps,
+		moduleState,
+		moduleData,
+		isCompleting,
+		isCompleted: completedRef.current,
+		configurationError,
+		completionError,
+		completionReason,
+		context: contextValue,
+		updateDraft,
+		validateCurrentStep,
+		complete,
+		next,
+		back,
+		getState,
+		registerModuleHandle,
+		getModuleHandle
+	};
+	return /* @__PURE__ */ React.createElement(SelectionFlowProvider, { value: contextValue }, children(controller));
+};
+const ForwardedSelectionFlow = forwardRef(SelectionFlow);
+ForwardedSelectionFlow.displayName = "PisellSelectionFlow";
+//#endregion
+export { ForwardedSelectionFlow as default };

package/es/components/PisellSelectionFlow/compiler.d.ts

@@ -0,0 +1,12 @@
+import { CompiledSelectionFlowStep, SelectionFlowContextValue, SelectionFlowDraftAdapter, SelectionFlowModuleAdapter, SelectionFlowModuleRegistry, SelectionFlowStepConfig } from "./types.js";
+
+//#region src/components/PisellSelectionFlow/compiler.d.ts
+type AnyAdapter = SelectionFlowModuleAdapter<any, any, string, string, any, any>;
+type AnyRegistry = Record<string, AnyAdapter>;
+declare const resolveFlowModuleAdapter: <TDraft, TDraftUpdate, TField extends string, TModuleType extends string, TServices, THostContext>(registry: SelectionFlowModuleRegistry<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>, type: string) => AnyAdapter;
+declare const hasSelectionDraftFieldValue: <TDraft, TDraftUpdate, TField extends string>(draftAdapter: SelectionFlowDraftAdapter<TDraft, TDraftUpdate, TField>, draft: Readonly<TDraft>, field: TField) => boolean;
+declare const compileSelectionFlowSteps: <TDraft, TDraftUpdate, TField extends string, TModuleType extends string, TServices, THostContext>(steps: readonly SelectionFlowStepConfig<TModuleType>[], context: SelectionFlowContextValue<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>, dependencySeedDraft: Readonly<TDraft>, registry: SelectionFlowModuleRegistry<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>, draftAdapter: SelectionFlowDraftAdapter<TDraft, TDraftUpdate, TField>) => readonly CompiledSelectionFlowStep<TModuleType>[];
+declare const compileSelectionFlow: <TDraft, TDraftUpdate, TField extends string, TModuleType extends string, TServices, THostContext>(steps: readonly SelectionFlowStepConfig<TModuleType>[], context: SelectionFlowContextValue<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>, dependencySeedDraft: Readonly<TDraft>, registry: SelectionFlowModuleRegistry<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>, draftAdapter: SelectionFlowDraftAdapter<TDraft, TDraftUpdate, TField>) => readonly CompiledSelectionFlowStep<TModuleType>[];
+declare const isSelectionModuleType: (registry: AnyRegistry, type: string) => boolean;
+//#endregion
+export { compileSelectionFlow, compileSelectionFlowSteps, hasSelectionDraftFieldValue, isSelectionModuleType, resolveFlowModuleAdapter };

package/es/components/PisellSelectionFlow/compiler.js

@@ -0,0 +1,174 @@
+import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
+import { SelectionFlowCompileError } from "./types.js";
+//#region src/components/PisellSelectionFlow/compiler.ts
+const resolveFlowModuleAdapter = (registry, type) => registry[type];
+const hasSelectionDraftFieldValue = (draftAdapter, draft, field) => {
+	const value = draftAdapter.getFieldValue(draft, field);
+	if (value === null || typeof value === "undefined" || value === "") return false;
+	return !Array.isArray(value) || value.length > 0;
+};
+const normalizeModule = (input, stepKey, stepIndex, moduleIndex) => {
+	const config = typeof input === "string" ? { type: input } : input;
+	return _objectSpread2(_objectSpread2({}, config), {}, {
+		key: config.key || config.type,
+		stepKey,
+		stepIndex,
+		moduleIndex
+	});
+};
+const findCircularRequirements = (modules, registry, draftAdapter, initialDraft) => {
+	const providers = /* @__PURE__ */ new Map();
+	modules.forEach((module) => {
+		var _resolveFlowModuleAda;
+		(_resolveFlowModuleAda = resolveFlowModuleAdapter(registry, module.type)) === null || _resolveFlowModuleAda === void 0 || (_resolveFlowModuleAda = _resolveFlowModuleAda.provides) === null || _resolveFlowModuleAda === void 0 || _resolveFlowModuleAda.forEach((field) => {
+			providers.set(field, [...providers.get(field) || [], module]);
+		});
+	});
+	const resolved = /* @__PURE__ */ new Set();
+	let progressed = true;
+	while (progressed) {
+		progressed = false;
+		for (const module of modules) {
+			if (resolved.has(module.key)) continue;
+			const adapter = resolveFlowModuleAdapter(registry, module.type);
+			if (!((adapter === null || adapter === void 0 ? void 0 : adapter.hardRequires) || []).every((field) => {
+				const candidates = (providers.get(field) || []).filter((provider) => provider.key !== module.key);
+				if (candidates.length === 0) return hasSelectionDraftFieldValue(draftAdapter, initialDraft, field);
+				return candidates.some((provider) => resolved.has(provider.key));
+			})) continue;
+			resolved.add(module.key);
+			progressed = true;
+		}
+	}
+	const unresolved = modules.filter((module) => !resolved.has(module.key));
+	if (unresolved.length === 0) return null;
+	return unresolved.some((module) => {
+		var _resolveFlowModuleAda2;
+		return (((_resolveFlowModuleAda2 = resolveFlowModuleAdapter(registry, module.type)) === null || _resolveFlowModuleAda2 === void 0 ? void 0 : _resolveFlowModuleAda2.hardRequires) || []).some((field) => {
+			return (providers.get(field) || []).filter((provider) => provider.key !== module.key).length === 0 && !hasSelectionDraftFieldValue(draftAdapter, initialDraft, field);
+		});
+	}) ? null : unresolved.map((module) => module.type);
+};
+const compileSelectionFlowSteps = (steps, context, dependencySeedDraft, registry, draftAdapter) => {
+	const issues = [];
+	const stepKeys = /* @__PURE__ */ new Set();
+	const moduleKeys = /* @__PURE__ */ new Set();
+	const compiledSteps = [];
+	steps.forEach((step, sourceStepIndex) => {
+		const stepKey = String(step.key || "").trim();
+		if (!stepKey || stepKeys.has(stepKey)) issues.push({
+			code: "DUPLICATE_STEP_KEY",
+			message: stepKey ? `Selection flow contains duplicate step key "${stepKey}".` : "Selection flow step key cannot be empty.",
+			stepKey: stepKey || void 0
+		});
+		else stepKeys.add(stepKey);
+		if (!Array.isArray(step.modules) || step.modules.length === 0) {
+			issues.push({
+				code: "EMPTY_STEP",
+				message: `Selection flow step "${stepKey || sourceStepIndex}" has no modules.`,
+				stepKey: stepKey || void 0
+			});
+			return;
+		}
+		const applicableModules = [];
+		step.modules.forEach((input) => {
+			const module = normalizeModule(input, stepKey, compiledSteps.length, applicableModules.length);
+			const adapter = resolveFlowModuleAdapter(registry, module.type);
+			if (!adapter) {
+				issues.push({
+					code: "UNKNOWN_MODULE",
+					message: `Selection module type "${module.type}" is not registered.`,
+					stepKey,
+					moduleKey: module.key,
+					moduleType: module.type
+				});
+				return;
+			}
+			if (moduleKeys.has(module.key)) {
+				issues.push({
+					code: "DUPLICATE_MODULE_KEY",
+					message: `Selection flow contains duplicate module key "${module.key}".`,
+					stepKey,
+					moduleKey: module.key,
+					moduleType: module.type
+				});
+				return;
+			}
+			moduleKeys.add(module.key);
+			try {
+				if (adapter.isApplicable && !adapter.isApplicable(context, module)) return;
+			} catch (error) {
+				issues.push({
+					code: "APPLICABILITY_CHECK_FAILED",
+					message: `Selection module "${module.type}" applicability check failed: ${error instanceof Error ? error.message : String(error)}`,
+					stepKey,
+					moduleKey: module.key,
+					moduleType: module.type
+				});
+				return;
+			}
+			applicableModules.push(_objectSpread2(_objectSpread2({}, module), {}, { moduleIndex: applicableModules.length }));
+		});
+		if (applicableModules.length === 0) return;
+		const index = compiledSteps.length;
+		compiledSteps.push(_objectSpread2(_objectSpread2({}, step), {}, {
+			key: stepKey,
+			index,
+			modules: applicableModules.map((module) => _objectSpread2(_objectSpread2({}, module), {}, { stepIndex: index }))
+		}));
+	});
+	const flatModules = compiledSteps.flatMap((step) => [...step.modules]);
+	if (flatModules.length === 0 && steps.length === 0) issues.push({
+		code: "EMPTY_FLOW",
+		message: "Selection flow has no applicable modules."
+	});
+	const circularPath = findCircularRequirements(flatModules, registry, draftAdapter, dependencySeedDraft);
+	if (circularPath) issues.push({
+		code: "CIRCULAR_HARD_REQUIREMENT",
+		message: `Selection flow contains unresolvable circular hard requirements among: ${circularPath.join(", ")}.`,
+		moduleType: circularPath[0]
+	});
+	const providers = /* @__PURE__ */ new Map();
+	flatModules.forEach((module, index) => {
+		var _resolveFlowModuleAda3;
+		(_resolveFlowModuleAda3 = resolveFlowModuleAdapter(registry, module.type)) === null || _resolveFlowModuleAda3 === void 0 || (_resolveFlowModuleAda3 = _resolveFlowModuleAda3.provides) === null || _resolveFlowModuleAda3 === void 0 || _resolveFlowModuleAda3.forEach((field) => {
+			providers.set(field, [...providers.get(field) || [], {
+				module,
+				index
+			}]);
+		});
+	});
+	flatModules.forEach((module, index) => {
+		const adapter = resolveFlowModuleAdapter(registry, module.type);
+		for (const field of (adapter === null || adapter === void 0 ? void 0 : adapter.hardRequires) || []) {
+			const typedField = field;
+			const fieldProviders = (providers.get(typedField) || []).filter((provider) => provider.module.key !== module.key);
+			if (fieldProviders.length === 0) {
+				if (hasSelectionDraftFieldValue(draftAdapter, dependencySeedDraft, typedField)) continue;
+				issues.push({
+					code: "MISSING_HARD_REQUIREMENT",
+					message: `Selection module "${module.type}" requires Draft field "${typedField}", but no earlier module provides it.`,
+					stepKey: module.stepKey,
+					moduleKey: module.key,
+					moduleType: module.type,
+					requirementField: typedField
+				});
+				continue;
+			}
+			if (!fieldProviders.some((provider) => provider.index < index)) issues.push({
+				code: "INVALID_DEPENDENCY_ORDER",
+				message: `Selection module "${module.type}" requires Draft field "${typedField}" to be provided before it.`,
+				stepKey: module.stepKey,
+				moduleKey: module.key,
+				moduleType: module.type,
+				requirementField: typedField
+			});
+		}
+	});
+	if (issues.length > 0) throw new SelectionFlowCompileError(issues);
+	return compiledSteps;
+};
+const compileSelectionFlow = compileSelectionFlowSteps;
+const isSelectionModuleType = (registry, type) => Boolean(registry[type]);
+//#endregion
+export { compileSelectionFlow, compileSelectionFlowSteps, hasSelectionDraftFieldValue, isSelectionModuleType, resolveFlowModuleAdapter };

package/es/components/PisellSelectionFlow/context.d.ts

@@ -0,0 +1,9 @@
+import { SelectionFlowContextValue } from "./types.js";
+import React from "react";
+
+//#region src/components/PisellSelectionFlow/context.d.ts
+type AnySelectionFlowContext = SelectionFlowContextValue<any, any, string, string, any, any>;
+declare const useSelectionFlowContext: () => AnySelectionFlowContext;
+declare const useTypedSelectionFlowContext: <TDraft, TDraftUpdate, TField extends string, TModuleType extends string, TServices = unknown, THostContext = unknown>() => SelectionFlowContextValue<TDraft, TDraftUpdate, TField, TModuleType, TServices, THostContext>;
+//#endregion
+export { useSelectionFlowContext, useTypedSelectionFlowContext };

package/es/components/PisellSelectionFlow/context.js

@@ -0,0 +1,12 @@
+import React, { createContext, useContext } from "react";
+//#region src/components/PisellSelectionFlow/context.tsx
+const SelectionFlowReactContext = createContext(null);
+const SelectionFlowProvider = ({ value, children }) => /* @__PURE__ */ React.createElement(SelectionFlowReactContext.Provider, { value }, children);
+const useSelectionFlowContext = () => {
+	const context = useContext(SelectionFlowReactContext);
+	if (!context) throw new Error("useSelectionFlowContext must be used inside PisellSelectionFlow");
+	return context;
+};
+const useTypedSelectionFlowContext = () => useSelectionFlowContext();
+//#endregion
+export { SelectionFlowProvider, useSelectionFlowContext, useTypedSelectionFlowContext };

package/es/components/PisellSelectionFlow/hooks/useFlowDraft.js

@@ -0,0 +1,35 @@
+import { _objectSpread2 } from "../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
+import { useCallback, useRef, useState } from "react";
+//#region src/components/PisellSelectionFlow/hooks/useFlowDraft.ts
+/** 统一管理不可变 Draft 与业务自定义合并策略。 */
+const useFlowDraft = ({ initialDraft, draftAdapter, mountedRef, draftRevisionRef, onDraftChangeRef, processDraftChangeRef }) => {
+	const [draft, setDraft] = useState(() => initialDraft);
+	const draftRef = useRef(draft);
+	draftRef.current = draft;
+	return {
+		draft,
+		draftRef,
+		updateDraft: useCallback((update, meta) => {
+			var _onDraftChangeRef$cur;
+			if (!mountedRef.current) return;
+			const previousDraft = draftRef.current;
+			const nextDraft = draftAdapter.applyUpdate(previousDraft, update);
+			draftRevisionRef.current += 1;
+			draftRef.current = nextDraft;
+			setDraft(nextDraft);
+			(_onDraftChangeRef$cur = onDraftChangeRef.current) === null || _onDraftChangeRef$cur === void 0 || _onDraftChangeRef$cur.call(onDraftChangeRef, nextDraft);
+			processDraftChangeRef.current(_objectSpread2({
+				previousDraft,
+				draft: nextDraft
+			}, meta));
+		}, [
+			draftAdapter,
+			draftRevisionRef,
+			mountedRef,
+			onDraftChangeRef,
+			processDraftChangeRef
+		])
+	};
+};
+//#endregion
+export { useFlowDraft };