@primafuture/contrib-kit-react 1.0.0

package/src/extension-outlet.ts

@@ -0,0 +1,590 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+import * as react from "react";
+
+import type * as adapterConfiguration from "./internal/adapter-configuration.js";
+import type * as outletCommitLease from "./internal/outlet-commit-lease.js";
+import * as outletErrorPipeline from "./internal/outlet-error-pipeline.js";
+import * as outletInput from "./internal/outlet-input.js";
+import * as outletMembership from "./internal/outlet-membership.js";
+import * as outletMembershipBoundary from "./internal/outlet-membership-boundary.js";
+import * as outletProjection from "./internal/outlet-projection.js";
+import * as reactAdapterDiagnostics from "./react-adapter-diagnostics.js";
+import type * as reactExtensionPoint from "./react-extension-point.js";
+import * as resolvedContributions from "./resolved-contributions.js";
+
+/**
+ * Společný frozen render state jedné logical outlet membership.
+ *
+ * @public
+ */
+export interface ExtensionContributionRenderStateBase<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Context exact outlet resolution snapshotu. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Bezpečný public contribution view bez registration identity. */
+	readonly contribution: import("./contribution-component.js").ExtensionContributionView<
+		contribKitCore.ExtensionPointData<Point>
+	>;
+	/** Outlet-local logická pozice ve finálním Core pořadí. */
+	readonly placement: import("./contribution-component.js").ResolvedContributionPlacement;
+	/** Exact canonical React extension point. */
+	readonly point: Point;
+}
+
+/**
+ * Frozen render state eager nebo již načtené contribution.
+ *
+ * @public
+ */
+export interface ExtensionContributionReadyRenderState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> extends ExtensionContributionRenderStateBase<Point> {
+	/** Exact ověřená React contribution component reference. */
+	readonly component: import("./contribution-component.js").ReactContributionComponent<
+		contribKitCore.ExtensionPointContext<Point>,
+		contribKitCore.ExtensionPointData<Point>
+	>;
+	/** Frozen default-render props sdílející tutéž placement referenci. */
+	readonly componentProps: import("./contribution-component.js").ExtensionContributionProps<
+		contribKitCore.ExtensionPointContext<Point>,
+		contribKitCore.ExtensionPointData<Point>
+	>;
+}
+
+/**
+ * Frozen render state dosud nenačtené managed-lazy membership.
+ *
+ * @public
+ */
+export interface ExtensionContributionLoadingRenderState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> extends ExtensionContributionRenderStateBase<Point> {}
+
+/**
+ * Frozen render state izolované contribution chyby.
+ *
+ * @public
+ */
+export interface ExtensionContributionErrorRenderState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> extends ExtensionContributionRenderStateBase<Point> {
+	/** Tentýž frozen primary event použitý sinkem a policy. */
+	readonly error: import("./react-adapter-diagnostics.js").ReactAdapterErrorEvent;
+	/** Generation-bound recovery command dané membership. */
+	retry(): void;
+}
+
+/**
+ * Placement-free frozen stav úspěšného prázdného outletu.
+ *
+ * @public
+ */
+export interface ExtensionEmptyRenderState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Context úspěšného empty resolution snapshotu. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Exact canonical point. */
+	readonly point: Point;
+	/** Rozlišení prázdného katalogu od policy-excluded výsledku. */
+	readonly reason: import("./resolved-contributions.js").ExtensionOutletEmptyReason;
+}
+
+/**
+ * Placement-free frozen stav neúspěšného outlet resolution.
+ *
+ * @public
+ */
+export interface ExtensionResolveErrorRenderState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Context neúspěšného query attemptu. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Frozen primary resolve event. */
+	readonly error: import("./react-adapter-diagnostics.js").ReactAdapterErrorEvent;
+	/** Exact canonical point. */
+	readonly point: Point;
+	/** Stabilní outlet-local invalidace bez Core commitu. */
+	refresh(): void;
+}
+
+/**
+ * Frozen discriminovaná recovery capability doručená outlet `onError` callbacku.
+ *
+ * @public
+ */
+export type ExtensionOutletErrorEmission =
+	| {
+		/** Rozlišuje per-membership chybu. */
+		readonly kind: "contribution";
+		/** Frozen primary contribution event. */
+		readonly error: import("./react-adapter-diagnostics.js").ReactAdapterErrorEvent;
+		/** Generation-bound membership retry. */
+		retry(): void;
+	}
+	| {
+		/** Rozlišuje celý failed resolve attempt. */
+		readonly kind: "resolve";
+		/** Frozen primary resolve event. */
+		readonly error: import("./react-adapter-diagnostics.js").ReactAdapterErrorEvent;
+		/** Stabilní outlet-local refresh command. */
+		refresh(): void;
+	};
+
+/**
+ * Frozen evidence jednoho committed accepted membership retry.
+ *
+ * @public
+ */
+export interface ExtensionOutletRetryEvent {
+	/** Opaque scope-local boundary identita. */
+	readonly boundaryId: string;
+	/** Veřejná contribution identita bez business dat. */
+	readonly contributionId: string;
+	/** Opaque scope-local outlet identita. */
+	readonly outletId: string;
+	/** Veřejná point identita. */
+	readonly pointId: string;
+	/** Opaque exact Core activation identita. */
+	readonly registrationId: string;
+	/** Nově committed monotonická retry generation. */
+	readonly retryGeneration: number;
+}
+
+/**
+ * Read-once props headless outletu inferované z exact React pointu.
+ *
+ * @public
+ */
+export interface ExtensionOutletProps<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Context předaný Core resolution pipeline a contribution props. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Lokální contribution policy; null obnoví package default. */
+	readonly errorPolicy?: import("./react-adapter-diagnostics.js").ReactErrorPolicy | null | undefined;
+	/** False eskaluje contribution failure bez policy izolace. */
+	readonly isolateErrors?: boolean | undefined;
+	/** Committed error callback s omezenou retry nebo refresh capability. */
+	readonly onError?: ((event: ExtensionOutletErrorEmission) => void) | undefined;
+	/** Callback až po commitu accepted retry generation. */
+	readonly onRetry?: ((event: ExtensionOutletRetryEvent) => void) | undefined;
+	/** Exact canonical React extension point. */
+	readonly point: Point;
+	/** Lokální pure context projector; null zruší inherited projector. */
+	readonly projectContext?: (
+		(context: contribKitCore.ExtensionPointContext<Point>) => unknown
+	) | null | undefined;
+	/** Explicitní registry s předností před nearest providerem. */
+	readonly registry?: contribKitCore.ExtensionRegistry | undefined;
+	/** Optional headless renderer ready membershipu. */
+	readonly renderContribution?: ((
+		state: ExtensionContributionReadyRenderState<Point>,
+	) => react.ReactNode) | undefined;
+	/** Optional fallback renderer izolované contribution chyby. */
+	readonly renderContributionError?: ((
+		state: ExtensionContributionErrorRenderState<Point>,
+	) => react.ReactNode) | undefined;
+	/** Optional renderer úspěšného prázdného výsledku. */
+	readonly renderEmpty?: ((state: ExtensionEmptyRenderState<Point>) => react.ReactNode) | undefined;
+	/** Optional renderer managed-lazy loading membershipu. */
+	readonly renderLoading?: ((
+		state: ExtensionContributionLoadingRenderState<Point>,
+	) => react.ReactNode) | undefined;
+	/** Optional renderer celého resolve failure. */
+	readonly renderResolveError?: ((
+		state: ExtensionResolveErrorRenderState<Point>,
+	) => react.ReactNode) | undefined;
+	/** Lokální diagnostic sink; null obnoví bezpečný package fallback. */
+	readonly sink?: import("./react-adapter-diagnostics.js").ReactAdapterSink | null | undefined;
+}
+
+/** Vstup outlet-level rendereru bez contribution identity. */
+interface OutletGlobalRendererProps {
+	/** Read-once captured renderer callback. */
+	readonly render: outletInput.CapturedOutletCallback<unknown, react.ReactNode>;
+	/** Frozen empty nebo resolve-error render state. */
+	readonly state: unknown;
+}
+
+/** Vstup sink-only outlet-level reporter boundary. */
+interface OutletGlobalReporterProps<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** React subtree host rendereru. */
+	readonly children: react.ReactNode;
+	/** Effective sink konfigurace outletu. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Exact generation resetující stale reporter state. */
+	readonly generationToken: object;
+	/** Current query/outlet authority. */
+	readonly isCurrent: () => boolean;
+	/** Optional committed outlet lease. */
+	readonly outletLease: outletCommitLease.OutletCommitLease | undefined;
+	/** Exact canonical point pro bezpečná metadata. */
+	readonly point: Point;
+}
+
+/** State outlet reporteru oddělující capture, report a exact escalation. */
+interface OutletGlobalReporterState {
+	/** Captured host renderer cause. */
+	readonly cause: unknown;
+	/** Exact cause připravený pro následující host escalation. */
+	readonly escalationCause: unknown;
+	/** Rozlišuje skutečně captured undefined cause. */
+	readonly hasFailure: boolean;
+	/** Zda následující render musí eskalovat. */
+	readonly hasEscalation: boolean;
+	/** Exact render generation owning current state. */
+	readonly generationToken: object;
+}
+
+/** Props committed hostu atomicky držícího poslední membership snapshot. */
+interface OutletCommittedHostProps<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Sdílený hook/scope binding current renderu. */
+	readonly binding: resolvedContributions.OutletResolvedContributionsBinding<Point>;
+	/** Pure outlet projection current renderu. */
+	readonly projection: outletProjection.OutletProjectionSnapshot<Point>;
+}
+
+/** Class state představující pouze atomicky odvozený membership snapshot. */
+interface OutletCommittedHostState<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Poslední React state derivací přijatý immutable snapshot. */
+	readonly snapshot: outletMembership.OutletMembershipSnapshot<Point>;
+	/** Poslední autoritativní lease a raw registry pro Activity-only state retention. */
+	readonly retainedLease:
+		| {
+			/** Lease, která byla v některém předchozím commitu current. */
+			readonly lease: outletCommitLease.OutletCommitLease;
+			/** Raw registry identita, pro kterou byla lease přijata. */
+			readonly rawRegistry: object;
+		}
+		| undefined;
+}
+
+/** Render effectu pro committed resolve `onError`. */
+interface OutletResolveCallbackAttempt<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Exact sdílený hook binding current renderu. */
+	readonly binding: resolvedContributions.OutletResolvedContributionsBinding<Point>;
+	/** Read-once outlet input včetně callbacku. */
+	readonly input: outletInput.CapturedOutletInput<Point>;
+}
+
+/** Vytvoří čistý outlet reporter state pro novou render generation. */
+function createGlobalReporterState(generationToken: object): OutletGlobalReporterState {
+	return {
+		cause: undefined,
+		escalationCause: undefined,
+		hasFailure: false,
+		hasEscalation: false,
+		generationToken,
+	};
+}
+
+/** Volá host renderer s undefined receiverem uvnitř jeho reporter boundary. */
+function OutletGlobalRenderer(props: OutletGlobalRendererProps): react.ReactElement {
+	const rendered = outletInput.callCapturedOutletCallback(props.render, props.state);
+	return react.createElement(react.Fragment, null, rendered);
+}
+
+/**
+ * Outlet-level class boundary reportující custom renderer chybu bez contribution policy.
+ */
+class OutletGlobalReporterBoundary<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends react.Component<OutletGlobalReporterProps<Point>, OutletGlobalReporterState> {
+	/** State začíná bez failure v exact projection generation. */
+	public override state = createGlobalReporterState(this.props.generationToken);
+
+	/** Zachytí host renderer cause bez sink side effectu. */
+	public static getDerivedStateFromError(cause: unknown): Partial<OutletGlobalReporterState> {
+		return { cause, hasFailure: true, hasEscalation: false };
+	}
+
+	/** Resetuje reporter dříve, než renderuje novou projection generation. */
+	public static getDerivedStateFromProps(
+		props: OutletGlobalReporterProps<reactExtensionPoint.AnyReactExtensionPoint>,
+		state: OutletGlobalReporterState,
+	): OutletGlobalReporterState | null {
+		return props.generationToken === state.generationToken
+			? null
+			: createGlobalReporterState(props.generationToken);
+	}
+
+	/** Reportuje committed failure právě jednou a připraví exact escalation. */
+	public override componentDidCatch(cause: unknown, info: react.ErrorInfo): void {
+		if (!this.state.hasFailure || !this.props.isCurrent()) {
+			return;
+		}
+		const point = reactAdapterDiagnostics.createPointMetadata(this.props.point);
+		const reactComponentStack = outletErrorPipeline.normalizeReactComponentStack(
+			info.componentStack,
+		);
+		const outletId = this.props.outletLease?.isCurrent() === true
+			? this.props.outletLease.id
+			: undefined;
+		const event = reactAdapterDiagnostics.createReactAdapterErrorEvent({
+			code: "REACT_RENDER_FAILED",
+			cause,
+			phase: "customRender",
+			...(outletId === undefined ? {} : { outletId }),
+			...(point === undefined ? {} : { point }),
+			...(reactComponentStack === undefined ? {} : { reactComponentStack }),
+		});
+		reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+			reactAdapterDiagnostics.createErrorDiagnostic(event),
+			this.props.configuration,
+		);
+		if (this.props.isCurrent()) {
+			this.setState({ escalationCause: cause, hasEscalation: true });
+		}
+	}
+
+	/** Failed commit nejprve zobrazí null, další render vyhodí exact cause hostu. */
+	public override render(): react.ReactNode {
+		if (this.state.hasEscalation) {
+			throw this.state.escalationCause;
+		}
+		return this.state.hasFailure ? null : this.props.children;
+	}
+}
+
+/** Reportuje secondary callback failure bez změny primary resolve outcome. */
+function reportResolveCallbackFailure<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	attempt: OutletResolveCallbackAttempt<Point>,
+	cause: unknown,
+): void {
+	if (!attempt.binding.isCurrent()) {
+		return;
+	}
+	const point = reactAdapterDiagnostics.createPointMetadata(attempt.input.point);
+	const event = reactAdapterDiagnostics.createReactAdapterErrorEvent({
+		code: "REACT_CALLBACK_FAILED",
+		cause,
+		phase: "callback",
+		...(point === undefined ? {} : { point }),
+	});
+	reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+		reactAdapterDiagnostics.createErrorDiagnostic(event),
+		attempt.input.configuration,
+	);
+}
+
+/** Pohltí sync, Promise i hostile thenable výsledek resolve callbacku. */
+function consumeResolveCallbackResult<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	result: unknown,
+	attempt: OutletResolveCallbackAttempt<Point>,
+): void {
+	let reported = false;
+	/** Přeloží nejvýše jednu current rejection na secondary diagnostiku. */
+	function reportFailure(cause: unknown): void {
+		if (reported) {
+			return;
+		}
+		reported = true;
+		reportResolveCallbackFailure(attempt, cause);
+	}
+	try {
+		void Promise.resolve(result).catch(reportFailure);
+	} catch (cause: unknown) {
+		reportFailure(cause);
+	}
+}
+
+/** Renderuje outlet-level empty nebo resolve-error callback pod reporter boundary. */
+function renderGlobalProjection<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	binding: resolvedContributions.OutletResolvedContributionsBinding<Point>,
+	render: outletInput.CapturedOutletCallback<unknown, react.ReactNode> | undefined,
+	state: unknown,
+	generationToken: object,
+): react.ReactElement | null {
+	if (render === undefined) {
+		return null;
+	}
+	const children = react.createElement(OutletGlobalRenderer, { render, state });
+	const outletLease = binding.outletLease;
+	/** Ověří query i případnou committed outlet lease bez jejího vytvoření. */
+	function isCurrent(): boolean {
+		return binding.isCurrent()
+			&& (outletLease === undefined || outletLease.isCurrent());
+	}
+	return react.createElement(OutletGlobalReporterBoundary<Point>, {
+		children,
+		configuration: binding.input.configuration,
+		generationToken,
+		isCurrent,
+		outletLease,
+		point: binding.input.point,
+	});
+}
+
+/**
+ * Class host publikuje jeden celý membership proposal místo render-time ref mutací.
+ */
+class OutletCommittedHost<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends react.Component<OutletCommittedHostProps<Point>, OutletCommittedHostState<Point>> {
+	/** První snapshot vzniká čistě z initial props bez commit-owned resource. */
+	public override state: OutletCommittedHostState<Point> = {
+		snapshot: outletMembership.reconcileOutletMemberships(
+			undefined,
+			this.props.binding.rawRegistry,
+			this.props.projection,
+		),
+		retainedLease: undefined,
+	};
+
+	/** Odvodí celý nový immutable proposal před jediným React state publish. */
+	public static getDerivedStateFromProps(
+		props: OutletCommittedHostProps<reactExtensionPoint.AnyReactExtensionPoint>,
+		state: OutletCommittedHostState<reactExtensionPoint.AnyReactExtensionPoint>,
+	): OutletCommittedHostState<reactExtensionPoint.AnyReactExtensionPoint> {
+		const outletLease = props.binding.outletLease;
+		return {
+			snapshot: outletMembership.reconcileOutletMemberships(
+				state.snapshot,
+				props.binding.rawRegistry,
+				props.projection,
+			),
+			retainedLease: outletLease?.isCurrent() === true
+				? Object.freeze({
+					lease: outletLease,
+					rawRegistry: props.binding.rawRegistry,
+				})
+				: state.retainedLease,
+		};
+	}
+
+	/** Renderuje placement-free global stav nebo ordered membership Fragment. */
+	public override render(): react.ReactElement | null {
+		const binding = this.props.binding;
+		const snapshot = this.state.snapshot;
+		if (snapshot.projection.kind === "resolveFailed") {
+			return renderGlobalProjection(
+				binding,
+				binding.input.renderResolveError,
+				snapshot.projection.renderState,
+				snapshot.projection,
+			);
+		}
+		const outletLease = binding.outletLease;
+		const retainsActivitySubtree = snapshot.rawRegistry === binding.rawRegistry
+			&& this.state.retainedLease?.rawRegistry === binding.rawRegistry
+			&& this.state.retainedLease.lease === outletLease;
+		// Inaktivní lease při Activity reveal smí držet pouze subtree stejné registry.
+		// Registry switch zůstává null bariérou a resetuje membership state; callback
+		// a resource autoritu v retained větvi nadále střeží current-lease gate boundary.
+		if ((outletLease === undefined && !binding.serverSnapshot)
+			|| (outletLease !== undefined
+				&& !outletLease.isCurrent()
+				&& !retainsActivitySubtree)) {
+			return null;
+		}
+		if (snapshot.projection.kind === "empty") {
+			return renderGlobalProjection(
+				binding,
+				binding.input.renderEmpty,
+				snapshot.projection.renderState,
+				snapshot.projection,
+			);
+		}
+		const generation = binding.generation;
+		if (generation === undefined) {
+			return null;
+		}
+		return react.createElement(
+			react.Fragment,
+			null,
+			...snapshot.memberships.map(
+				/** Vytvoří samostatnou keyed package boundary v exact Core pořadí. */
+				function renderMembership(membership): react.ReactElement {
+					return react.createElement(
+						outletMembershipBoundary.OutletMembershipBoundary<Point>,
+						{
+							key: membership.seed.registrationId,
+							input: binding.input,
+							membership,
+							outletLease,
+							rawRegistry: binding.rawRegistry,
+							scope: binding.scope,
+							scopeGeneration: generation,
+						},
+					);
+				},
+			),
+		);
+	}
+}
+
+/**
+ * Renderuje exact Core resolved kolekci jako headless React Fragment.
+ *
+ * @public
+ */
+export function ExtensionOutlet<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+>(
+	props: ExtensionOutletProps<Point>,
+): react.ReactElement | null {
+	const [reportedResolveAttempts] = react.useState(
+		/** Vytvoří outlet-local Strict dedup ledger bez global historie. */
+		function createResolveAttemptLedger(): WeakSet<object> {
+			return new WeakSet<object>();
+		},
+	);
+	/** Doručí resolve callback z engine effectu až po committed sink diagnostice. */
+	function reportCommittedResolveError(
+		binding: resolvedContributions.OutletResolvedContributionsBinding<Point>,
+	): void {
+		const current: OutletResolveCallbackAttempt<Point> = Object.freeze({
+			binding,
+			input: binding.input,
+		});
+		if (current.input.onError === undefined
+			|| current.binding.attempt.state.status !== "failed"
+			|| !current.binding.isCurrent()
+			|| reportedResolveAttempts.has(current.binding.attempt.token)) {
+			return;
+		}
+		reportedResolveAttempts.add(current.binding.attempt.token);
+		const emission: ExtensionOutletErrorEmission = Object.freeze({
+			kind: "resolve",
+			error: current.binding.attempt.state.error,
+			refresh: current.binding.result.refresh,
+		});
+		try {
+			const result = outletInput.callCapturedOutletCallback(
+				current.input.onError,
+				emission,
+			);
+			consumeResolveCallbackResult(result, current);
+		} catch (cause: unknown) {
+			reportResolveCallbackFailure(current, cause);
+		}
+	}
+
+	const binding = resolvedContributions.useResolvedContributionsForOutlet<Point>(
+		props,
+		reportCommittedResolveError,
+	);
+	const projection = outletProjection.projectOutletSnapshot(
+		binding.input.point,
+		binding.input.context,
+		binding.result,
+		binding.checkpoint,
+	);
+	return react.createElement(OutletCommittedHost<Point>, { binding, projection });
+}