@primafuture/contrib-kit-react 1.0.0

package/src/internal/outlet-input.ts

@@ -0,0 +1,264 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+import type * as react from "react";
+
+import * as adapterConfiguration from "./adapter-configuration.js";
+import * as publicInputCapture from "./public-input-capture.js";
+import * as reactAdapterError from "../react-adapter-error.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+
+/** Interní render callback zachycený bez změny původní reference. */
+export type CapturedOutletCallback<Argument, Result> = (argument: Argument) => Result;
+
+/** Immutable read-once vstup budoucího headless outletu. */
+export interface CapturedOutletInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Exact canonical point předaný budoucímu resolved hooku. */
+	readonly point: Point;
+	/** Point-specific context zachycený pro jeden render attempt. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Explicitní nebo inherited raw registry vstup bez vzniklé subscription. */
+	readonly registry: unknown;
+	/** Zda budoucí membership boundary izoluje contribution render chyby. */
+	readonly isolateErrors: boolean;
+	/** Efektivní outlet-local konfigurace se zachovaným provider inheritance. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Optional custom renderer ready membershipu. */
+	readonly renderContribution: CapturedOutletCallback<unknown, react.ReactNode> | undefined;
+	/** Optional custom renderer loading membershipu. */
+	readonly renderLoading: CapturedOutletCallback<unknown, react.ReactNode> | undefined;
+	/** Optional custom renderer contribution failure. */
+	readonly renderContributionError: CapturedOutletCallback<unknown, react.ReactNode> | undefined;
+	/** Optional custom renderer úspěšného prázdného výsledku. */
+	readonly renderEmpty: CapturedOutletCallback<unknown, react.ReactNode> | undefined;
+	/** Optional custom renderer resolve failure. */
+	readonly renderResolveError: CapturedOutletCallback<unknown, react.ReactNode> | undefined;
+	/** Optional callback budoucího committed error emission. */
+	readonly onError: CapturedOutletCallback<unknown, unknown> | undefined;
+	/** Optional callback budoucího committed retry eventu. */
+	readonly onRetry: CapturedOutletCallback<unknown, unknown> | undefined;
+}
+
+/** Lifecycle checkpoint mezi user-observable capture kroky. */
+export type OutletInputCaptureCheckpoint = () => void;
+
+/** Výchozí resource-free checkpoint interního čistého capture. */
+function skipOutletInputCaptureCheckpoint(): void {
+	// Volající bez lifecycle autority nepotřebuje další gate.
+}
+
+/** Ověří exact point jako non-null objekt bez čtení jeho polí. */
+function requireOutletPoint<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(value: unknown): Point {
+	if (typeof value !== "object" || value === null) {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_INVALID_ARGUMENT",
+			"props.point must be a non-null object.",
+			{ details: { field: "props.point", phase: "configuration" } },
+		);
+	}
+
+	return value as Point;
+}
+
+/** Normalizuje optional isolate flag bez truthy/falsy coercion. */
+function captureIsolateErrors(value: unknown): boolean {
+	if (value === undefined) {
+		return true;
+	}
+	if (typeof value !== "boolean") {
+		return publicInputCapture.throwInvalidCapturedArgument(
+			"props.isolateErrors",
+			"props.isolateErrors must be a boolean when provided.",
+		);
+	}
+
+	return value;
+}
+
+/** Ověří optional outlet callback bez jeho zavolání nebo přebalení. */
+function captureOptionalOutletCallback<Argument, Result>(
+	value: unknown,
+	field:
+		| "renderContribution"
+		| "renderLoading"
+		| "renderContributionError"
+		| "renderEmpty"
+		| "renderResolveError"
+		| "onError"
+		| "onRetry",
+): CapturedOutletCallback<Argument, Result> | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "function") {
+		return publicInputCapture.throwInvalidCapturedArgument(
+			`props.${field}`,
+			`props.${field} must be callable when provided.`,
+		);
+	}
+
+	return value as CapturedOutletCallback<Argument, Result>;
+}
+
+/**
+ * Zachytí budoucí outlet props v normativním pořadí bez vytvoření resource.
+ */
+export function captureOutletInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	props: object,
+	inheritedRegistry: unknown | undefined,
+	inheritedConfiguration: adapterConfiguration.AdapterScopeConfiguration | undefined,
+	checkpoint: OutletInputCaptureCheckpoint = skipOutletInputCaptureCheckpoint,
+): CapturedOutletInput<Point> {
+	const source = publicInputCapture.requireInputObject(props, "props");
+	const pointValue = publicInputCapture.readInputProperty(
+		source,
+		"point",
+		"props.point",
+		checkpoint,
+	);
+	const context = publicInputCapture.readInputProperty(
+		source,
+		"context",
+		"props.context",
+		checkpoint,
+	) as contribKitCore.ExtensionPointContext<Point>;
+	const registryValue = publicInputCapture.readInputProperty(
+		source,
+		"registry",
+		"props.registry",
+		checkpoint,
+	);
+	const isolateErrorsValue = publicInputCapture.readInputProperty(
+		source,
+		"isolateErrors",
+		"props.isolateErrors",
+		checkpoint,
+	);
+	const sinkValue = publicInputCapture.readInputProperty(
+		source,
+		"sink",
+		"props.sink",
+		checkpoint,
+	);
+	const errorPolicyValue = publicInputCapture.readInputProperty(
+		source,
+		"errorPolicy",
+		"props.errorPolicy",
+		checkpoint,
+	);
+	const projectContextValue = publicInputCapture.readInputProperty(
+		source,
+		"projectContext",
+		"props.projectContext",
+		checkpoint,
+	);
+	const renderContributionValue = publicInputCapture.readInputProperty(
+		source,
+		"renderContribution",
+		"props.renderContribution",
+		checkpoint,
+	);
+	const renderLoadingValue = publicInputCapture.readInputProperty(
+		source,
+		"renderLoading",
+		"props.renderLoading",
+		checkpoint,
+	);
+	const renderContributionErrorValue = publicInputCapture.readInputProperty(
+		source,
+		"renderContributionError",
+		"props.renderContributionError",
+		checkpoint,
+	);
+	const renderEmptyValue = publicInputCapture.readInputProperty(
+		source,
+		"renderEmpty",
+		"props.renderEmpty",
+		checkpoint,
+	);
+	const renderResolveErrorValue = publicInputCapture.readInputProperty(
+		source,
+		"renderResolveError",
+		"props.renderResolveError",
+		checkpoint,
+	);
+	const onErrorValue = publicInputCapture.readInputProperty(
+		source,
+		"onError",
+		"props.onError",
+		checkpoint,
+	);
+	const onRetryValue = publicInputCapture.readInputProperty(
+		source,
+		"onRetry",
+		"props.onRetry",
+		checkpoint,
+	);
+
+	const point = requireOutletPoint<Point>(pointValue);
+	const isolateErrors = captureIsolateErrors(isolateErrorsValue);
+	const registry = adapterConfiguration.resolveAdapterRegistryInput(
+		registryValue,
+		inheritedRegistry,
+	);
+	const patch = adapterConfiguration.captureAdapterConfigurationPatch(
+		sinkValue,
+		errorPolicyValue,
+		projectContextValue,
+		checkpoint,
+	);
+	const configuration = adapterConfiguration.resolveAdapterScopeConfiguration(
+		inheritedConfiguration,
+		patch,
+	);
+	const renderContribution = captureOptionalOutletCallback<unknown, react.ReactNode>(
+		renderContributionValue,
+		"renderContribution",
+	);
+	const renderLoading = captureOptionalOutletCallback<unknown, react.ReactNode>(
+		renderLoadingValue,
+		"renderLoading",
+	);
+	const renderContributionError = captureOptionalOutletCallback<unknown, react.ReactNode>(
+		renderContributionErrorValue,
+		"renderContributionError",
+	);
+	const renderEmpty = captureOptionalOutletCallback<unknown, react.ReactNode>(
+		renderEmptyValue,
+		"renderEmpty",
+	);
+	const renderResolveError = captureOptionalOutletCallback<unknown, react.ReactNode>(
+		renderResolveErrorValue,
+		"renderResolveError",
+	);
+	const onError = captureOptionalOutletCallback<unknown, unknown>(onErrorValue, "onError");
+	const onRetry = captureOptionalOutletCallback<unknown, unknown>(onRetryValue, "onRetry");
+	checkpoint();
+
+	return Object.freeze({
+		point,
+		context,
+		registry,
+		isolateErrors,
+		configuration,
+		renderContribution,
+		renderLoading,
+		renderContributionError,
+		renderEmpty,
+		renderResolveError,
+		onError,
+		onRetry,
+	});
+}
+
+/** Zavolá již zachycený outlet callback vždy s `undefined` receiverem. */
+export function callCapturedOutletCallback<Argument, Result>(
+	callback: CapturedOutletCallback<Argument, Result>,
+	argument: Argument,
+): Result {
+	return Reflect.apply(callback, undefined, [argument]) as Result;
+}