@primafuture/contrib-kit-react 1.0.0

package/src/react-extension-point.ts

@@ -0,0 +1,181 @@
+import * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as implementationClassifier from "./internal/implementation-classifier.js";
+
+/** Immutable prázdný issues seznam vestavěného negativního výsledku. */
+const emptyValidationIssues: readonly contribKitCore.RuntimeValidationIssue[] = Object.freeze([]);
+
+/** Sdílený platný výsledek vestavěného classifier validátoru. */
+const validImplementationResult: contribKitCore.RuntimeValidationResult = Object.freeze({ valid: true });
+
+/** Sdílený negativní výsledek bez raw implementation hodnoty. */
+const invalidImplementationResult: contribKitCore.RuntimeValidationResult = Object.freeze({
+	valid: false,
+	issues: emptyValidationIssues,
+});
+
+/** Callable host validator zachycený přes transparentní Core capture. */
+type HostImplementationValidator = (value: unknown) => contribKitCore.RuntimeValidationResult;
+
+/**
+ * Spustí vestavěnou React implementation klasifikaci bez obalení accessor chyby.
+ */
+function validateReactImplementation(value: unknown): contribKitCore.RuntimeValidationResult {
+	return implementationClassifier.classifyReactContributionImplementation(value).kind === "invalid"
+		? invalidImplementationResult
+		: validImplementationResult;
+}
+
+/**
+ * Rozpozná hodnotu, kterou lze transparentně obalit Proxy bez předčasného čtení.
+ */
+function isProxyTarget(value: unknown): value is object {
+	return (typeof value === "object" && value !== null) || typeof value === "function";
+}
+
+/**
+ * Vytvoří validator facade, jehož jediný `validate` Get zachytí host callback.
+ */
+function createImplementationValidatorFacade(value: unknown): unknown {
+	if (value === undefined) {
+		return Object.freeze({ validate: validateReactImplementation });
+	}
+	if (!isProxyTarget(value)) {
+		return value;
+	}
+
+	return new Proxy(Object.create(null) as object, {
+		get(_target, property): unknown {
+			const captured = Reflect.get(value, property, value);
+			if (property !== "validate") {
+				return captured;
+			}
+			if (captured === undefined) {
+				return validateReactImplementation;
+			}
+			if (typeof captured !== "function") {
+				return captured;
+			}
+
+			const hostValidate = captured as HostImplementationValidator;
+			return (implementation: unknown): contribKitCore.RuntimeValidationResult => {
+				const builtIn = validateReactImplementation(implementation);
+				return builtIn.valid ? hostValidate(implementation) : builtIn;
+			};
+		},
+	});
+}
+
+/**
+ * Doplní pouze implementation validator a ostatní nested fields transparentně předá.
+ */
+function createValidatorsFacade(value: unknown): unknown {
+	if (value === undefined) {
+		return Object.freeze({
+			implementation: Object.freeze({ validate: validateReactImplementation }),
+		});
+	}
+	if (!isProxyTarget(value)) {
+		return value;
+	}
+
+	return new Proxy(Object.create(null) as object, {
+		get(_target, property): unknown {
+			const captured = Reflect.get(value, property, value);
+			return property === "implementation"
+				? createImplementationValidatorFacade(captured)
+				: captured;
+		},
+	});
+}
+
+/**
+ * Vytvoří transparentní definition facade; samotný read-once capture vlastní Core.
+ */
+function createDefinitionFacade(value: unknown): unknown {
+	if (!isProxyTarget(value)) {
+		return value;
+	}
+
+	return new Proxy(Object.create(null) as object, {
+		get(_target, property): unknown {
+			const captured = Reflect.get(value, property, value);
+			return property === "validators" ? createValidatorsFacade(captured) : captured;
+		},
+	});
+}
+
+/**
+ * React-specific extension point with an eager or managed-lazy implementation axis.
+ *
+ * @public
+ */
+export type ReactExtensionPoint<
+	Context,
+	Data,
+	PointId extends string = string,
+	ContractVersion extends number = number,
+> = contribKitCore.ExtensionPoint<
+	Context,
+	Data,
+	import("./react-lazy-contribution.js").ReactContributionImplementation<Context, Data>,
+	PointId,
+	ContractVersion
+>;
+
+/**
+ * Any React extension point accepted by generic adapter APIs.
+ *
+ * @public
+ */
+export type AnyReactExtensionPoint = ReactExtensionPoint<any, any, any, any>;
+
+/**
+ * Core point definition specialized for React contribution implementations.
+ *
+ * @public
+ */
+export type ReactExtensionPointDefinition<
+	Context,
+	Data,
+	PointId extends string,
+	ContractVersion extends number,
+> = contribKitCore.ExtensionPointDefinition<
+	Context,
+	Data,
+	import("./react-lazy-contribution.js").ReactContributionImplementation<Context, Data>,
+	PointId,
+	ContractVersion
+>;
+
+/**
+ * Creates an authentic Core point with a built-in React implementation validator.
+ *
+ * @public
+ */
+export function defineReactExtensionPoint<Context, Data>(): <
+	const PointId extends string,
+	const ContractVersion extends number,
+>(
+	definition: ReactExtensionPointDefinition<Context, Data, PointId, ContractVersion>,
+	options?: contribKitCore.ExtensionPointFactoryOptions,
+) => ReactExtensionPoint<Context, Data, PointId, ContractVersion> {
+	const defineCorePoint = contribKitCore.defineExtensionPoint<
+		Context,
+		Data,
+		import("./react-lazy-contribution.js").ReactContributionImplementation<Context, Data>
+	>();
+
+	return <const PointId extends string, const ContractVersion extends number>(
+		definition: ReactExtensionPointDefinition<Context, Data, PointId, ContractVersion>,
+		options?: contribKitCore.ExtensionPointFactoryOptions,
+	): ReactExtensionPoint<Context, Data, PointId, ContractVersion> => defineCorePoint(
+		createDefinitionFacade(definition) as ReactExtensionPointDefinition<
+			Context,
+			Data,
+			PointId,
+			ContractVersion
+		>,
+		options,
+	);
+}

package/src/react-lazy-contribution.ts

@@ -0,0 +1,66 @@
+import * as publicInputCapture from "./internal/public-input-capture.js";
+
+/**
+ * Input for one managed-lazy loader attempt.
+ *
+ * @public
+ */
+export interface ReactLazyContributionLoadInput {
+	/** Abort signal owned by the specific render boundary generation. */
+	readonly signal: import("@primafuture/contrib-kit-core").ContributionAbortSignal;
+}
+
+/**
+ * Public input for the managed-lazy contribution convenience factory.
+ *
+ * @public
+ */
+export interface ReactLazyContributionInput<Context, Data> {
+	/** Loads a React contribution component for one boundary-owned attempt. */
+	readonly load: (
+		input: ReactLazyContributionLoadInput,
+	) => Promise<import("./contribution-component.js").ReactContributionComponent<Context, Data>>;
+}
+
+/**
+ * Structural managed-lazy descriptor recognizable across two adapter runtimes.
+ *
+ * @public
+ */
+export interface ReactLazyContribution<Context, Data>
+	extends ReactLazyContributionInput<Context, Data> {
+	/** Reserved literal that distinguishes the descriptor from an eager React component. */
+	readonly kind: "contrib-kit-react-lazy";
+}
+
+/**
+ * Implementation axis of a React extension point.
+ *
+ * @public
+ */
+export type ReactContributionImplementation<Context, Data> =
+	| import("./contribution-component.js").ReactContributionComponent<Context, Data>
+	| ReactLazyContribution<Context, Data>;
+
+/**
+ * Captures the loader exactly once and creates a shallow-frozen structural descriptor.
+ *
+ * @public
+ */
+export function defineReactLazyContribution<Context, Data>(
+	input: ReactLazyContributionInput<Context, Data>,
+): ReactLazyContribution<Context, Data> {
+	const source = publicInputCapture.requireInputObject(input, "input");
+	const load = publicInputCapture.readInputProperty(source, "load", "input.load");
+	if (typeof load !== "function") {
+		return publicInputCapture.throwInvalidCapturedArgument(
+			"input.load",
+			"input.load must be callable.",
+		);
+	}
+
+	return Object.freeze({
+		kind: "contrib-kit-react-lazy" as const,
+		load: load as ReactLazyContributionInput<Context, Data>["load"],
+	});
+}