@primafuture/contrib-kit-react 1.0.0

package/src/extension-registry-provider.ts

@@ -0,0 +1,179 @@
+import * as contribKitCore from "@primafuture/contrib-kit-core";
+import * as react from "react";
+
+import * as adapterConfiguration from "./internal/adapter-configuration.js";
+import * as adapterContext from "./internal/adapter-context.js";
+import * as adapterRegistryProtocol from "./internal/adapter-registry-protocol.js";
+import * as adapterScope from "./internal/adapter-scope.js";
+import * as publicInputCapture from "./internal/public-input-capture.js";
+import * as reactAdapterError from "./react-adapter-error.js";
+
+/**
+ * Props tree-local React adapter scope bez převzetí Core ownershipu.
+ *
+ * @public
+ */
+export interface ExtensionRegistryProviderProps {
+	/** React subtree, kterému provider zpřístupní registry a konfiguraci. */
+	readonly children?: react.ReactNode;
+	/** Inherited contribution policy; null obnoví package default. */
+	readonly errorPolicy?: import("./react-adapter-diagnostics.js").ReactErrorPolicy | null | undefined;
+	/** Pure projekce host contextu použitelná pouze v diagnostice. */
+	readonly projectContext?: ((context: unknown) => unknown) | null | undefined;
+	/** Hostem vlastněná Core registry; provider ji nikdy nedisposuje. */
+	readonly registry: contribKitCore.ExtensionRegistry;
+	/** Inherited command-free sink; null obnoví console fallback. */
+	readonly sink?: import("./react-adapter-diagnostics.js").ReactAdapterSink | null | undefined;
+}
+
+/** Úspěšný read-once provider capture pro jeden render attempt. */
+interface CapturedProviderRender {
+	/** Rozlišuje validní Context hodnotu od synchronní configuration chyby. */
+	readonly ok: true;
+	/** Frozen Context hodnota publikovaná pouze committed React tree. */
+	readonly contextValue: adapterContext.AdapterContextValue;
+	/** Provider children přečtené jako poslední známé pole. */
+	readonly children: react.ReactNode;
+}
+
+/** Neúspěšný provider capture držený do zavolání všech interních hooks. */
+interface FailedProviderRender {
+	/** Rozlišuje synchronní configuration failure. */
+	readonly ok: false;
+	/** Přesná adapter chyba se zachovaným accessor cause. */
+	readonly error: unknown;
+}
+
+/** Jeden provider render po úplném hook-order-safe capture. */
+type ProviderRender = CapturedProviderRender | FailedProviderRender;
+
+/**
+ * Vytvoří nový resource-free scope pouze jako lokální React state.
+ */
+function createProviderScope(): adapterScope.AdapterScopeRuntime {
+	return new adapterScope.AdapterScopeRuntime();
+}
+
+/**
+ * Zachytí všechna známá provider pole v normativním pořadí bez partial Contextu.
+ */
+function captureProviderRender(
+	props: ExtensionRegistryProviderProps,
+	parent: adapterContext.AdapterContextValue | undefined,
+	scope: adapterScope.AdapterScopeRuntime,
+	checkpoint: () => void,
+): CapturedProviderRender {
+	const source = publicInputCapture.requireInputObject(props, "props");
+	const registryValue = publicInputCapture.readInputProperty(
+		source,
+		"registry",
+		"props.registry",
+		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 children = publicInputCapture.readInputProperty(
+		source,
+		"children",
+		"props.children",
+		checkpoint,
+	) as react.ReactNode;
+	const protocol = adapterRegistryProtocol.captureAdapterRegistryProtocol(
+		registryValue,
+		checkpoint,
+	);
+	const patch = adapterConfiguration.captureAdapterConfigurationPatch(
+		sinkValue,
+		errorPolicyValue,
+		projectContextValue,
+		checkpoint,
+	);
+	const configuration = adapterConfiguration.resolveAdapterScopeConfiguration(
+		parent?.generation.configuration,
+		patch,
+	);
+	checkpoint();
+	const generation = adapterScope.createAdapterScopeGeneration(protocol, configuration);
+	return Object.freeze({
+		ok: true,
+		children,
+		contextValue: adapterContext.createAdapterContextValue(scope, generation),
+	});
+}
+
+/**
+ * Poskytne tree-local registry a adapter konfiguraci bez DOM wrapperu nebo Core dispose.
+ *
+ * @public
+ */
+export function ExtensionRegistryProvider(
+	props: ExtensionRegistryProviderProps,
+): react.ReactElement {
+	const parent = adapterContext.useAdapterContext();
+	const [scope] = react.useState(createProviderScope);
+	const renderSerial = react.useRef(0);
+	renderSerial.current += 1;
+	const currentRenderSerial = renderSerial.current;
+	/** Ověří, že reentrantní host seam nezneplatnil právě probíhající capture. */
+	function checkpointProviderRender(): void {
+		if (renderSerial.current !== currentRenderSerial) {
+			throw new reactAdapterError.ReactAdapterError(
+				"REACT_ADAPTER_DISPOSED",
+				"The provider render attempt is no longer current.",
+				{ details: { field: "provider.render", phase: "lifecycle" } },
+			);
+		}
+	}
+
+	let captured: ProviderRender;
+	try {
+		captured = captureProviderRender(props, parent, scope, checkpointProviderRender);
+	} catch (error: unknown) {
+		captured = Object.freeze({ ok: false, error });
+	}
+
+	const generation = captured.ok ? captured.contextValue.generation : undefined;
+	react.useEffect(
+		/** Committed provider lifecycle vlastní pouze adapter scope owner lease. */
+		function acquireProviderScope(): void | (() => void) {
+			if (generation === undefined || renderSerial.current !== currentRenderSerial) {
+				return undefined;
+			}
+			return scope.acquireOwner(generation);
+		},
+		[
+			scope,
+			generation?.defaultProtocol.rawRegistry,
+			generation?.defaultProtocol.registryId,
+			generation?.configuration.sink?.receiver,
+			generation?.configuration.sink?.report,
+			generation?.configuration.errorPolicy,
+			generation?.configuration.projectContext,
+		],
+	);
+
+	if (!captured.ok) {
+		throw captured.error;
+	}
+
+	return adapterContext.createAdapterContextProvider(
+		captured.contextValue,
+		captured.children,
+	);
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Public React adapter contracts for typed components, managed-lazy descriptors,
+ * and authentic Core extension points.
+ *
+ * @packageDocumentation
+ */
+
+export { defineReactContributionComponent } from "./contribution-component.js";
+export { ExtensionOutlet } from "./extension-outlet.js";
+export { ExtensionRegistryProvider } from "./extension-registry-provider.js";
+export { ReactAdapterError } from "./react-adapter-error.js";
+export { defineReactExtensionPoint } from "./react-extension-point.js";
+export { defineReactLazyContribution } from "./react-lazy-contribution.js";
+export { useResolvedContributions } from "./resolved-contributions.js";
+
+export type {
+	ExtensionContributionProps,
+	ExtensionContributionView,
+	ReactContributionComponent,
+	ResolvedContributionPlacement,
+} from "./contribution-component.js";
+
+export type {
+	ExtensionContributionErrorRenderState,
+	ExtensionContributionLoadingRenderState,
+	ExtensionContributionReadyRenderState,
+	ExtensionContributionRenderStateBase,
+	ExtensionEmptyRenderState,
+	ExtensionOutletErrorEmission,
+	ExtensionOutletProps,
+	ExtensionOutletRetryEvent,
+	ExtensionResolveErrorRenderState,
+} from "./extension-outlet.js";
+
+export type {
+	ExtensionRegistryProviderProps,
+} from "./extension-registry-provider.js";
+
+export type {
+	ReactAdapterDiagnosticEvent,
+	ReactAdapterErrorEvent,
+	ReactAdapterSink,
+	ReactErrorAction,
+	ReactErrorPolicy,
+	ReadonlyContributionMetadata,
+	ReadonlyPointMetadata,
+} from "./react-adapter-diagnostics.js";
+
+export type {
+	ReactAdapterErrorCode,
+	ReactAdapterErrorPhase,
+} from "./react-adapter-error.js";
+
+export type {
+	AnyReactExtensionPoint,
+	ReactExtensionPoint,
+	ReactExtensionPointDefinition,
+} from "./react-extension-point.js";
+
+export type {
+	ReactContributionImplementation,
+	ReactLazyContribution,
+	ReactLazyContributionInput,
+	ReactLazyContributionLoadInput,
+} from "./react-lazy-contribution.js";
+
+export type {
+	ExtensionOutletEmptyReason,
+	ResolvedContributionsState,
+	UseResolvedContributionsOptions,
+	UseResolvedContributionsResult,
+} from "./resolved-contributions.js";

package/src/internal/adapter-configuration.ts

@@ -0,0 +1,181 @@
+import * as publicInputCapture from "./public-input-capture.js";
+import * as reactAdapterError from "../react-adapter-error.js";
+
+/** Read-once zachycený diagnostický sink včetně původního receiveru. */
+export interface CapturedReactAdapterSink {
+	/** Původní strukturální receiver host callbacku. */
+	readonly receiver: object;
+	/** Stabilní reference jediného známého sink callbacku. */
+	readonly report: (event: unknown) => unknown;
+}
+
+/** Interní error-policy callback před materializací veřejného event typu. */
+export type CapturedReactErrorPolicy = (error: unknown) => unknown;
+
+/** Interní context projector před materializací veřejného event typu. */
+export type CapturedReactContextProjector = (context: unknown) => unknown;
+
+/** Efektivní immutable konfigurace jednoho adapter scope generation. */
+export interface AdapterScopeConfiguration {
+	/** Custom sink nebo absence znamenající package fallback. */
+	readonly sink: CapturedReactAdapterSink | undefined;
+	/** Custom contribution error policy nebo package default. */
+	readonly errorPolicy: CapturedReactErrorPolicy | undefined;
+	/** Optional bezpečná projekce host contextu do diagnostiky. */
+	readonly projectContext: CapturedReactContextProjector | undefined;
+}
+
+/** Tri-state patch zachovávající inheritance a explicitní null clear. */
+export interface CapturedAdapterConfigurationPatch {
+	/** `undefined` dědí, `null` ruší custom sink. */
+	readonly sink: CapturedReactAdapterSink | null | undefined;
+	/** `undefined` dědí, `null` obnovuje package policy. */
+	readonly errorPolicy: CapturedReactErrorPolicy | null | undefined;
+	/** `undefined` dědí, `null` projector vypíná. */
+	readonly projectContext: CapturedReactContextProjector | null | undefined;
+}
+
+/** Lifecycle checkpoint spuštěný po každém nested public Getu. */
+export type AdapterConfigurationCheckpoint = () => void;
+
+/** Prázdná package konfigurace bez custom host callbacku. */
+export const EMPTY_ADAPTER_SCOPE_CONFIGURATION: AdapterScopeConfiguration = Object.freeze({
+	sink: undefined,
+	errorPolicy: undefined,
+	projectContext: undefined,
+});
+
+/**
+ * Zachytí optional sink a jeho jediný známý callback se správným receiverem.
+ */
+function captureSink(
+	value: unknown,
+	checkpoint: AdapterConfigurationCheckpoint,
+): CapturedReactAdapterSink | null | undefined {
+	if (value === undefined || value === null) {
+		return value;
+	}
+
+	const receiver = publicInputCapture.requireInputObject(value, "options.sink");
+	const report = publicInputCapture.readInputProperty(
+		receiver,
+		"report",
+		"options.sink.report",
+		checkpoint,
+	);
+	if (typeof report !== "function") {
+		return publicInputCapture.throwInvalidCapturedArgument(
+			"options.sink.report",
+			"options.sink.report must be callable.",
+		);
+	}
+
+	return Object.freeze({
+		receiver,
+		report: report as (event: unknown) => unknown,
+	});
+}
+
+/**
+ * Ověří optional callable configuration bez čtení dalších public polí.
+ */
+function captureOptionalCallback<Callback extends (value: unknown) => unknown>(
+	value: unknown,
+	field: "errorPolicy" | "projectContext",
+): Callback | null | undefined {
+	if (value === undefined || value === null) {
+		return value;
+	}
+	if (typeof value !== "function") {
+		return publicInputCapture.throwInvalidCapturedArgument(
+			`options.${field}`,
+			`options.${field} must be callable.`,
+		);
+	}
+
+	return value as Callback;
+}
+
+/**
+ * Zvaliduje již read-once zachycené hodnoty bez dalšího čtení parent options.
+ */
+export function captureAdapterConfigurationPatch(
+	sinkValue: unknown,
+	errorPolicyValue: unknown,
+	projectContextValue: unknown,
+	checkpoint: AdapterConfigurationCheckpoint,
+): CapturedAdapterConfigurationPatch {
+	return Object.freeze({
+		sink: captureSink(sinkValue, checkpoint),
+		errorPolicy: captureOptionalCallback<CapturedReactErrorPolicy>(
+			errorPolicyValue,
+			"errorPolicy",
+		),
+		projectContext: captureOptionalCallback<CapturedReactContextProjector>(
+			projectContextValue,
+			"projectContext",
+		),
+	});
+}
+
+/**
+ * Vyřeší každou config osu samostatně nad nearest provider konfigurací.
+ */
+export function resolveAdapterScopeConfiguration(
+	parent: AdapterScopeConfiguration | undefined,
+	patch: CapturedAdapterConfigurationPatch,
+): AdapterScopeConfiguration {
+	return Object.freeze({
+		sink: patch.sink === undefined ? parent?.sink : patch.sink ?? undefined,
+		errorPolicy: patch.errorPolicy === undefined
+			? parent?.errorPolicy
+			: patch.errorPolicy ?? undefined,
+		projectContext: patch.projectContext === undefined
+			? parent?.projectContext
+			: patch.projectContext ?? undefined,
+	});
+}
+
+/**
+ * Porovná dvě efektivní konfigurace pouze přes zachycené capability reference.
+ */
+export function isSameAdapterScopeConfiguration(
+	left: AdapterScopeConfiguration,
+	right: AdapterScopeConfiguration,
+): boolean {
+	return left.sink?.receiver === right.sink?.receiver
+		&& left.sink?.report === right.sink?.report
+		&& left.errorPolicy === right.errorPolicy
+		&& left.projectContext === right.projectContext;
+}
+
+/**
+ * Vybere explicitní registry bez silent fallbacku nebo nearest provider default.
+ */
+export function resolveAdapterRegistryInput(
+	explicitRegistry: unknown,
+	inheritedRegistry: unknown | undefined,
+): unknown {
+	if (explicitRegistry !== undefined) {
+		return explicitRegistry;
+	}
+	if (inheritedRegistry !== undefined) {
+		return inheritedRegistry;
+	}
+
+	throw new reactAdapterError.ReactAdapterError(
+		"REACT_REGISTRY_NOT_PROVIDED",
+		"No extension registry was provided.",
+		{ details: { field: "options.registry", phase: "configuration" } },
+	);
+}
+
+/**
+ * Zavolá zachycený sink s původním receiverem; výsledek vlastní vyšší pipeline.
+ */
+export function callCapturedReactAdapterSink(
+	sink: CapturedReactAdapterSink,
+	event: unknown,
+): unknown {
+	return Reflect.apply(sink.report, sink.receiver, [event]);
+}

package/src/internal/adapter-context.ts

@@ -0,0 +1,43 @@
+import * as react from "react";
+
+import * as adapterScope from "./adapter-scope.js";
+
+/**
+ * Immutable provider value oddělující stabilní scope od aktuální generation.
+ */
+export interface AdapterContextValue {
+	/** Stabilní tree-local vlastník bridge a lifecycle zdrojů. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Aktuální provider registry a inherited konfigurace. */
+	readonly generation: adapterScope.AdapterScopeGeneration;
+}
+
+/** Modulově lokální Context capability bez process-global registry mapy. */
+const adapterContext = react.createContext<AdapterContextValue | undefined>(undefined);
+
+/**
+ * Vytvoří frozen Context value pro jeden provider render.
+ */
+export function createAdapterContextValue(
+	scope: adapterScope.AdapterScopeRuntime,
+	generation: adapterScope.AdapterScopeGeneration,
+): AdapterContextValue {
+	return Object.freeze({ scope, generation });
+}
+
+/**
+ * Vrátí nearest provider hodnotu při zachování standardního React Hook pořadí.
+ */
+export function useAdapterContext(): AdapterContextValue | undefined {
+	return react.useContext(adapterContext);
+}
+
+/**
+ * Vystaví interní Context provider bez přidání host DOM elementu.
+ */
+export function createAdapterContextProvider(
+	value: AdapterContextValue,
+	children: react.ReactNode,
+): react.ReactElement {
+	return react.createElement(adapterContext.Provider, { value }, children);
+}