@primafuture/contrib-kit-react 1.0.0

package/src/internal/outlet-reporter-boundary.ts

@@ -0,0 +1,105 @@
+import * as react from "react";
+
+import * as outletErrorPipeline from "./outlet-error-pipeline.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+
+/** Props sink-only reporter boundary kolem host fallback rendereru. */
+export interface OutletReporterBoundaryProps<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** React subtree, jehož failure se reportuje bez policy recursion. */
+	readonly children: react.ReactNode;
+	/** Metadata owning membership a committed diagnostic channelu. */
+	readonly errorInput: Omit<
+		outletErrorPipeline.OutletFallbackErrorInput<Point>,
+		"cause" | "reactComponentStack"
+	>;
+	/** Exact retry/error generation resetující reporter state. */
+	readonly generationToken: object;
+}
+
+/** Interní stav oddělující capture commit a následnou exact escalation. */
+interface OutletReporterBoundaryState {
+	/** Captured fallback cause čekající na componentDidCatch commit. */
+	readonly cause: unknown;
+	/** Cause připravený k throw z vlastní boundary render cesty. */
+	readonly escalationCause: unknown;
+	/** Zda state skutečně obsahuje captured failure i pro undefined cause. */
+	readonly hasFailure: boolean;
+	/** Zda má následující render eskalovat exact cause. */
+	readonly hasEscalation: boolean;
+	/** Generation, pro kterou state platí. */
+	readonly generationToken: object;
+}
+
+/** Vytvoří čistý reporter state bez failure. */
+function createReporterReadyState(generationToken: object): OutletReporterBoundaryState {
+	return {
+		cause: undefined,
+		escalationCause: undefined,
+		hasFailure: false,
+		hasEscalation: false,
+		generationToken,
+	};
+}
+
+/**
+ * Class boundary pro fallback/outlet renderer failure bez onError a policy recursion.
+ */
+export class OutletReporterBoundary<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends react.Component<
+	OutletReporterBoundaryProps<Point>,
+	OutletReporterBoundaryState
+> {
+	/** State začíná v exact render generation props. */
+	public override state: OutletReporterBoundaryState = createReporterReadyState(
+		this.props.generationToken,
+	);
+
+	/** Zachytí descendant failure bez user callbacku nebo sink side effectu. */
+	public static getDerivedStateFromError(cause: unknown): Partial<OutletReporterBoundaryState> {
+		return {
+			cause,
+			hasFailure: true,
+			hasEscalation: false,
+		};
+	}
+
+	/** Resetuje stale failure dříve, než se renderuje nová generation. */
+	public static getDerivedStateFromProps(
+		props: OutletReporterBoundaryProps<reactExtensionPoint.AnyReactExtensionPoint>,
+		state: OutletReporterBoundaryState,
+	): OutletReporterBoundaryState | null {
+		return props.generationToken === state.generationToken
+			? null
+			: createReporterReadyState(props.generationToken);
+	}
+
+	/** Commit point reportuje jednou a připraví exact escalation k host boundary. */
+	public override componentDidCatch(cause: unknown, info: react.ErrorInfo): void {
+		if (!this.state.hasFailure || !this.props.errorInput.isCurrent()) {
+			return;
+		}
+		const reactComponentStack = outletErrorPipeline.normalizeReactComponentStack(
+			info.componentStack,
+		);
+		const escalationCause = outletErrorPipeline.reportOutletFallbackError({
+			...this.props.errorInput,
+			cause,
+			...(reactComponentStack === undefined ? {} : { reactComponentStack }),
+		});
+		if (!this.props.errorInput.isCurrent()) {
+			return;
+		}
+		this.setState({ escalationCause, hasEscalation: true });
+	}
+
+	/** Failed commit nejprve renderuje null, následující render eskaluje exact cause. */
+	public override render(): react.ReactNode {
+		if (this.state.hasEscalation) {
+			throw this.state.escalationCause;
+		}
+		return this.state.hasFailure ? null : this.props.children;
+	}
+}

package/src/internal/public-input-capture.ts

@@ -0,0 +1,55 @@
+import * as reactAdapterError from "../react-adapter-error.js";
+
+/**
+ * Oveří strukturální public input před jediným čtením jeho známých polí.
+ */
+export function requireInputObject(value: unknown, inputName: string): object {
+	if ((typeof value !== "object" || value === null) && typeof value !== "function") {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_INVALID_ARGUMENT",
+			`${inputName} must be an object.`,
+			{ details: { field: inputName, phase: "configuration" } },
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Načte jedno známé pole právě jednou a zachová accessor/Proxy failure.
+ */
+export function readInputProperty(
+	target: object,
+	property: PropertyKey,
+	inputName: string,
+	checkpoint?: () => void,
+): unknown {
+	let value: unknown;
+	try {
+		value = Reflect.get(target, property, target);
+	} catch (cause: unknown) {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_INVALID_ARGUMENT",
+			`Unable to read ${inputName}.`,
+			{
+				cause,
+				details: { field: inputName, phase: "configuration" },
+			},
+		);
+	}
+
+	checkpoint?.();
+
+	return value;
+}
+
+/**
+ * Vytvoří jednotnou strukturální chybu již zachyceného public inputu.
+ */
+export function throwInvalidCapturedArgument(inputName: string, message: string): never {
+	throw new reactAdapterError.ReactAdapterError(
+		"REACT_INVALID_ARGUMENT",
+		message,
+		{ details: { field: inputName, phase: "configuration" } },
+	);
+}

package/src/internal/resolved-contributions-query.ts

@@ -0,0 +1,318 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as adapterConfiguration from "./adapter-configuration.js";
+import * as adapterRegistryProtocol from "./adapter-registry-protocol.js";
+import * as reactAdapterDiagnostics from "../react-adapter-diagnostics.js";
+import * as reactAdapterError from "../react-adapter-error.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+import type * as resolvedContributions from "../resolved-contributions.js";
+
+/** Sdílená frozen prázdná tuple použitá každým failed query výsledkem. */
+export const EMPTY_RESOLVED_CONTRIBUTIONS: readonly [] = Object.freeze([]);
+
+/** Jeden lokální render attempt bez externí resource identity. */
+export interface ResolvedQueryAttempt<Point extends reactExtensionPoint.AnyReactExtensionPoint> {
+	/** Opaque token používaný pouze committed diagnostic ledgerem. */
+	readonly token: object;
+	/** Frozen public state daného render attemptu. */
+	readonly state: resolvedContributions.ResolvedContributionsState<Point>;
+	/** Projector failure doručovaná před primary resolve diagnostikou. */
+	readonly secondaryDiagnostic?: reactAdapterDiagnostics.ReactAdapterDiagnosticEvent;
+	/** Primary resolve diagnostika přítomná právě pro failed state. */
+	readonly primaryDiagnostic?: reactAdapterDiagnostics.ReactAdapterDiagnosticEvent;
+}
+
+/** Vstupy jednoho synchronního Core list/resolve query. */
+export interface ResolvedQueryInput<Point extends reactExtensionPoint.AnyReactExtensionPoint> {
+	/** Exact captured registry protocol včetně původního receiveru. */
+	readonly protocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot;
+	/** Exact React point z public hook vstupu. */
+	readonly point: Point;
+	/** Point-specific context zachycený read-once z options. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Efektivní adapter konfigurace pro pure context projection. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** První bridge lifecycle fault, pokud již committed subscriber selhal. */
+	readonly bridgeFault?: reactAdapterError.ReactAdapterError;
+	/** Reentrantní authority checkpoint po každém host-observable seam. */
+	readonly checkpoint: () => void;
+}
+
+/** Bezpečně vytvoří resolve chybu bez vložení raw invalidní business hodnoty. */
+function createResolveError(
+	field: string,
+	cause?: unknown,
+	preserveCause = false,
+): reactAdapterError.ReactAdapterError {
+	return new reactAdapterError.ReactAdapterError(
+		"REACT_RESOLVE_FAILED",
+		"The resolved contribution collection is invalid.",
+		preserveCause
+			? { cause, details: { field, phase: "resolve" } }
+			: { details: { field, phase: "resolve" } },
+	);
+}
+
+/** Ověří structural array bez spuštění iterator user code. */
+function requireContributionArray(value: unknown, field: string): readonly unknown[] {
+	if (!Array.isArray(value)) {
+		throw createResolveError(field);
+	}
+
+	return value;
+}
+
+/** Přečte pouze délku raw katalogu potřebnou pro empty klasifikaci. */
+function readContributionArrayLength(
+	values: readonly unknown[],
+	field: string,
+	checkpoint: () => void,
+): number {
+	let length: unknown;
+	try {
+		length = Reflect.get(values, "length", values);
+	} catch (cause: unknown) {
+		throw createResolveError(`${field}.length`, cause, true);
+	}
+	checkpoint();
+	if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0) {
+		throw createResolveError(`${field}.length`);
+	}
+	return length;
+}
+
+/** Načte jedno známé record pole právě jednou a následně ověří autoritu. */
+function readContributionProperty(
+	record: object,
+	property:
+		| "point"
+		| "registrationId"
+		| "contributionId"
+		| "contributorId"
+		| "localName"
+		| "label"
+		| "implementation"
+		| "data",
+	field: string,
+	checkpoint: () => void,
+): unknown {
+	let value: unknown;
+	try {
+		value = Reflect.get(record, property, record);
+	} catch (cause: unknown) {
+		throw createResolveError(`${field}.${property}`, cause, true);
+	}
+	checkpoint();
+	return value;
+}
+
+/** Ověří optional contribution metadata jako primitive string. */
+function requireOptionalString(value: unknown, field: string): string | undefined {
+	if (value !== undefined && typeof value !== "string") {
+		throw createResolveError(field);
+	}
+
+	return value;
+}
+
+/** Zachytí jeden Core record bez neznámých polí a zachová business reference. */
+function captureContribution<Point extends reactExtensionPoint.AnyReactExtensionPoint>(
+	value: unknown,
+	point: Point,
+	field: string,
+	checkpoint: () => void,
+): contribKitCore.RegisteredContribution<Point> {
+	if (typeof value !== "object" || value === null) {
+		throw createResolveError(field);
+	}
+
+	const capturedPoint = readContributionProperty(value, "point", field, checkpoint);
+	const registrationId = readContributionProperty(value, "registrationId", field, checkpoint);
+	const contributionId = readContributionProperty(value, "contributionId", field, checkpoint);
+	const contributorId = readContributionProperty(value, "contributorId", field, checkpoint);
+	const localName = readContributionProperty(value, "localName", field, checkpoint);
+	const label = readContributionProperty(value, "label", field, checkpoint);
+	const implementation = readContributionProperty(value, "implementation", field, checkpoint);
+	const data = readContributionProperty(value, "data", field, checkpoint);
+
+	if (capturedPoint !== point) {
+		throw createResolveError(`${field}.point`);
+	}
+	if (typeof registrationId !== "string" || registrationId.length === 0) {
+		throw createResolveError(`${field}.registrationId`);
+	}
+	if (typeof contributionId !== "string" || contributionId.length === 0) {
+		throw createResolveError(`${field}.contributionId`);
+	}
+
+	return Object.freeze({
+		point,
+		registrationId,
+		contributionId,
+		...(requireOptionalString(contributorId, `${field}.contributorId`) === undefined
+			? {}
+			: { contributorId: contributorId as string }),
+		...(requireOptionalString(localName, `${field}.localName`) === undefined
+			? {}
+			: { localName: localName as string }),
+		...(requireOptionalString(label, `${field}.label`) === undefined
+			? {}
+			: { label: label as string }),
+		implementation: implementation as contribKitCore.ExtensionPointImplementation<Point>,
+		data: data as contribKitCore.ExtensionPointData<Point>,
+	});
+}
+
+/** Zachytí celou ordered kolekci a odmítne duplicitní registration identity. */
+function captureContributionArray<Point extends reactExtensionPoint.AnyReactExtensionPoint>(
+	value: unknown,
+	point: Point,
+	field: string,
+	checkpoint: () => void,
+): readonly contribKitCore.RegisteredContribution<Point>[] {
+	const source = requireContributionArray(value, field);
+	const captured: contribKitCore.RegisteredContribution<Point>[] = [];
+	const registrationIds = new Set<string>();
+	for (let index = 0; index < source.length; index += 1) {
+		let entry: unknown;
+		try {
+			entry = Reflect.get(source, index, source);
+		} catch (cause: unknown) {
+			throw createResolveError(`${field}[${index}]`, cause, true);
+		}
+		checkpoint();
+		const contribution = captureContribution(entry, point, `${field}[${index}]`, checkpoint);
+		if (registrationIds.has(contribution.registrationId)) {
+			throw createResolveError(`${field}[${index}].registrationId`);
+		}
+		registrationIds.add(contribution.registrationId);
+		captured.push(contribution);
+	}
+
+	return Object.freeze(captured);
+}
+
+/** Vytvoří primary a případnou secondary diagnostiku bez jejich doručení. */
+export function createFailedResolvedQueryAttempt<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	cause: unknown,
+	point: Point,
+	context: contribKitCore.ExtensionPointContext<Point>,
+	configuration: adapterConfiguration.AdapterScopeConfiguration,
+	checkpoint: () => void,
+): ResolvedQueryAttempt<Point> {
+	let primaryCause = cause;
+	let contextProjection: unknown;
+	let hasContextProjection = false;
+	let secondaryDiagnostic: reactAdapterDiagnostics.ReactAdapterDiagnosticEvent | undefined;
+
+	if (configuration.projectContext !== undefined) {
+		try {
+			contextProjection = Reflect.apply(configuration.projectContext, undefined, [context]);
+			hasContextProjection = true;
+		} catch (projectionCause: unknown) {
+			const pointMetadata = reactAdapterDiagnostics.createPointMetadata(point);
+			const projectionError = reactAdapterDiagnostics.createReactAdapterErrorEvent({
+				code: "REACT_CONTEXT_PROJECTION_FAILED",
+				phase: "projection",
+				cause: projectionCause,
+				...(pointMetadata === undefined ? {} : { point: pointMetadata }),
+			});
+			secondaryDiagnostic = reactAdapterDiagnostics.createErrorDiagnostic(projectionError);
+		}
+		if (hasContextProjection) {
+			try {
+				checkpoint();
+			} catch (authorityCause: unknown) {
+				primaryCause = authorityCause;
+				hasContextProjection = false;
+				contextProjection = undefined;
+			}
+		}
+	}
+
+	const coreCode = reactAdapterDiagnostics.readCoreErrorCode(primaryCause);
+	const code = reactAdapterDiagnostics.resolveReactErrorCode(primaryCause, coreCode);
+	const phase = reactAdapterDiagnostics.resolveReactErrorPhase(primaryCause);
+	const pointMetadata = reactAdapterDiagnostics.createPointMetadata(point);
+	const error = reactAdapterDiagnostics.createReactAdapterErrorEvent({
+		code,
+		phase,
+		cause: primaryCause,
+		...(coreCode === undefined ? {} : { coreCode }),
+		...(pointMetadata === undefined ? {} : { point: pointMetadata }),
+		contextProjection,
+		hasContextProjection,
+	});
+	const state: resolvedContributions.ResolvedContributionsState<Point> = Object.freeze({
+		status: "failed",
+		contributions: EMPTY_RESOLVED_CONTRIBUTIONS,
+		error,
+	});
+	return Object.freeze({
+		token: Object.freeze({}),
+		state,
+		...(secondaryDiagnostic === undefined ? {} : { secondaryDiagnostic }),
+		primaryDiagnostic: reactAdapterDiagnostics.createErrorDiagnostic(error),
+	});
+}
+
+/**
+ * Provede jeden synchronní list→resolve attempt a lokálně normalizuje jeho výsledek.
+ */
+export function queryResolvedContributions<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(input: ResolvedQueryInput<Point>): ResolvedQueryAttempt<Point> {
+	try {
+		if (input.bridgeFault !== undefined) {
+			throw input.bridgeFault;
+		}
+		adapterRegistryProtocol.requireAdapterRegistryAvailable(
+			input.protocol,
+			"resolve",
+			input.checkpoint,
+		);
+		const listed = adapterRegistryProtocol.listAdapterRegistryContributions(
+			input.protocol,
+			input.point,
+		);
+		input.checkpoint();
+		const resolved = adapterRegistryProtocol.resolveAdapterRegistryContributions(
+			input.protocol,
+			input.point,
+			input.context,
+		);
+		input.checkpoint();
+
+		const contributions = captureContributionArray(
+			resolved,
+			input.point,
+			"registry.resolveContributions()",
+			input.checkpoint,
+		);
+		const rawContributionCount = readContributionArrayLength(
+			requireContributionArray(listed, "registry.listContributions()"),
+			"registry.listContributions()",
+			input.checkpoint,
+		);
+		const state: resolvedContributions.ResolvedContributionsState<Point> = Object.freeze({
+			status: "resolved",
+			contributions,
+			emptyReason: contributions.length > 0
+				? null
+				: rawContributionCount === 0
+					? "noRegistrations"
+					: "excludedByPolicy",
+		});
+		return Object.freeze({ token: Object.freeze({}), state });
+	} catch (cause: unknown) {
+		return createFailedResolvedQueryAttempt(
+			cause,
+			input.point,
+			input.context,
+			input.configuration,
+			input.checkpoint,
+		);
+	}
+}