@primafuture/contrib-kit-react 1.0.0

package/src/internal/outlet-membership.ts

@@ -0,0 +1,125 @@
+import * as reactAdapterError from "../react-adapter-error.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+import type * as outletProjection from "./outlet-projection.js";
+
+/** Privátní compile-time identita opaque membership tokenu. */
+declare const outletMembershipTokenBrand: unique symbol;
+
+/** Render-pure opaque identita jedné outlet membership. */
+export interface OutletMembershipToken {
+	/** Privátní invariant bez runtime property nebo globálního brandu. */
+	readonly [outletMembershipTokenBrand]: "outlet-membership";
+}
+
+/** Jeden frozen membership candidate s přiděleným lokálním tokenem. */
+export interface OutletMembershipEntry<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Opaque token zachovaný pouze pro retained registry/registration tuple. */
+	readonly token: OutletMembershipToken;
+	/** Aktuální frozen render seed daného outlet snapshotu. */
+	readonly seed: outletProjection.OutletProjectedMembershipSeed<Point>;
+}
+
+/** Immutable čistý návrh jednoho outlet membership snapshotu. */
+export interface OutletMembershipSnapshot<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Exact raw registry reference jako první osa identity. */
+	readonly rawRegistry: object;
+	/** Atomický projection snapshot včetně placement-free větví. */
+	readonly projection: outletProjection.OutletProjectionSnapshot<Point>;
+	/** Ordered memberships; empty a resolve-failed projection používají prázdnou tuple. */
+	readonly memberships: readonly OutletMembershipEntry<Point>[];
+}
+
+/** Sdílená frozen prázdná membership tuple bez runtime historie. */
+const EMPTY_OUTLET_MEMBERSHIPS: readonly [] = Object.freeze([]);
+
+/** Vytvoří lokální opaque token bez external identity nebo side effectu. */
+function createOutletMembershipToken(): OutletMembershipToken {
+	return Object.freeze({}) as OutletMembershipToken;
+}
+
+/** Ověří raw registry identity bez čtení jejích public polí. */
+function requireRawRegistry(value: unknown): object {
+	if (typeof value !== "object" || value === null) {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_REGISTRY_INVALID",
+			"The outlet registry identity must be a non-null object.",
+			{ details: { field: "registry", phase: "configuration" } },
+		);
+	}
+	return value;
+}
+
+/** Zachytí reusable tokeny před vytvořením nového proposal snapshotu. */
+function collectRetainedTokens<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	previous: OutletMembershipSnapshot<Point> | undefined,
+	rawRegistry: object,
+): ReadonlyMap<string, OutletMembershipToken> {
+	const tokens = new Map<string, OutletMembershipToken>();
+	if (previous === undefined || previous.rawRegistry !== rawRegistry) {
+		return tokens;
+	}
+	for (const membership of previous.memberships) {
+		tokens.set(membership.seed.registrationId, membership.token);
+	}
+	return tokens;
+}
+
+/**
+ * Vytvoří atomický membership proposal bez zápisu do předchozího snapshotu.
+ */
+export function reconcileOutletMemberships<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	previous: OutletMembershipSnapshot<Point> | undefined,
+	rawRegistryValue: unknown,
+	projection: outletProjection.OutletProjectionSnapshot<Point>,
+): OutletMembershipSnapshot<Point> {
+	const rawRegistry = requireRawRegistry(rawRegistryValue);
+	if (projection.kind !== "memberships") {
+		return Object.freeze({
+			rawRegistry,
+			projection,
+			memberships: EMPTY_OUTLET_MEMBERSHIPS,
+		});
+	}
+
+	const registrationIds = new Set<string>();
+	for (const seed of projection.memberships) {
+		if (registrationIds.has(seed.registrationId)) {
+			throw new reactAdapterError.ReactAdapterError(
+				"REACT_RESOLVE_FAILED",
+				"The projected outlet collection contains duplicate registration identities.",
+				{
+					details: {
+						field: "projection.memberships.registrationId",
+						phase: "resolve",
+					},
+				},
+			);
+		}
+		registrationIds.add(seed.registrationId);
+	}
+
+	const retainedTokens = collectRetainedTokens(previous, rawRegistry);
+	const memberships = projection.memberships.map(
+		/** Připojí nový render seed k retained nebo čerstvému opaque tokenu. */
+		function createMembershipEntry(seed): OutletMembershipEntry<Point> {
+			return Object.freeze({
+				token: retainedTokens.get(seed.registrationId) ?? createOutletMembershipToken(),
+				seed,
+			});
+		},
+	);
+
+	return Object.freeze({
+		rawRegistry,
+		projection,
+		memberships: Object.freeze(memberships),
+	});
+}

package/src/internal/outlet-projection.ts

@@ -0,0 +1,511 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as implementationClassifier from "./implementation-classifier.js";
+import * as publicInputCapture from "./public-input-capture.js";
+import type * as contributionComponent from "../contribution-component.js";
+import * as reactAdapterError from "../react-adapter-error.js";
+import type * as reactAdapterDiagnostics from "../react-adapter-diagnostics.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+import type * as resolvedContributions from "../resolved-contributions.js";
+
+/** Společný frozen render vstup jedné projected membership. */
+export interface OutletContributionRenderSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Exact context jednoho outlet resolution snapshotu. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Bezpečný public contribution view bez runtime identity. */
+	readonly contribution: contributionComponent.ExtensionContributionView<
+		contribKitCore.ExtensionPointData<Point>
+	>;
+	/** Outlet-local logical placement odvozený z celé final kolekce. */
+	readonly placement: contributionComponent.ResolvedContributionPlacement;
+	/** Exact canonical point společný všem memberships snapshotu. */
+	readonly point: Point;
+}
+
+/** Frozen ready seed eager contribution. */
+export interface OutletReadyMembershipSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje eager ready větev od loading a failure. */
+	readonly kind: "ready";
+	/** Opaque Core registration identity dostupná pouze reconcileru. */
+	readonly registrationId: string;
+	/** Frozen ready render state včetně component props. */
+	readonly renderState: OutletContributionRenderSeed<Point> & {
+		/** Exact eager React component reference. */
+		readonly component: contributionComponent.ReactContributionComponent<
+			contribKitCore.ExtensionPointContext<Point>,
+			contribKitCore.ExtensionPointData<Point>
+		>;
+		/** Jediné tři frozen props budoucího default rendereru. */
+		readonly componentProps: contributionComponent.ExtensionContributionProps<
+			contribKitCore.ExtensionPointContext<Point>,
+			contribKitCore.ExtensionPointData<Point>
+		>;
+	};
+}
+
+/** Frozen loading seed managed-lazy contribution bez spuštěného loaderu. */
+export interface OutletLoadingMembershipSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje managed-lazy loading větev. */
+	readonly kind: "loading";
+	/** Opaque Core registration identity dostupná pouze reconcileru. */
+	readonly registrationId: string;
+	/** Zachycená loader reference bez invocation nebo controlleru. */
+	readonly load: implementationClassifier.CapturedReactLazyLoader;
+	/** Frozen loading render state bez raw implementation. */
+	readonly renderState: OutletContributionRenderSeed<Point>;
+}
+
+/** Frozen provisional failure seed neplatné contribution implementation. */
+export interface OutletFailedMembershipSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje per-membership classifier failure. */
+	readonly kind: "failed";
+	/** Opaque Core registration identity dostupná pouze reconcileru. */
+	readonly registrationId: string;
+	/** Stabilní adapter error připravená pro příští boundary checkpoint. */
+	readonly error: reactAdapterError.ReactAdapterError;
+	/** Frozen contribution render state bez raw implementation. */
+	readonly renderState: OutletContributionRenderSeed<Point>;
+}
+
+/** Jeden interní projected membership seed před přidělením identity tokenu. */
+export type OutletProjectedMembershipSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> =
+	| OutletReadyMembershipSeed<Point>
+	| OutletLoadingMembershipSeed<Point>
+	| OutletFailedMembershipSeed<Point>;
+
+/** Frozen placement-free stav úspěšného prázdného outletu. */
+export interface OutletEmptyProjection<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje empty stav od resolve failure a memberships. */
+	readonly kind: "empty";
+	/** Připravený budoucí render state bez placementu. */
+	readonly renderState: {
+		/** Exact context úspěšného prázdného query. */
+		readonly context: contribKitCore.ExtensionPointContext<Point>;
+		/** Exact canonical point. */
+		readonly point: Point;
+		/** Přesná úspěšná empty klasifikace hooku. */
+		readonly reason: resolvedContributions.ExtensionOutletEmptyReason;
+	};
+}
+
+/** Frozen placement-free stav outlet resolve failure. */
+export interface OutletResolveFailureProjection<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje resolve failure od empty stavu a memberships. */
+	readonly kind: "resolveFailed";
+	/** Připravený budoucí render state bez placementu. */
+	readonly renderState: {
+		/** Exact context neúspěšného query. */
+		readonly context: contribKitCore.ExtensionPointContext<Point>;
+		/** Frozen public error event z resolved hooku. */
+		readonly error: reactAdapterDiagnostics.ReactAdapterErrorEvent;
+		/** Exact canonical point. */
+		readonly point: Point;
+		/** Stabilní hook refresh capability. */
+		readonly refresh: () => void;
+	};
+}
+
+/** Frozen neprázdný ordered snapshot všech projected memberships. */
+export interface OutletResolvedProjection<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Rozlišuje neprázdný membership snapshot. */
+	readonly kind: "memberships";
+	/** Immutable seeds ve finálním Core resolved pořadí. */
+	readonly memberships: readonly OutletProjectedMembershipSeed<Point>[];
+}
+
+/** Atomický outlet projection candidate bez committed identity nebo resource. */
+export type OutletProjectionSnapshot<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> =
+	| OutletEmptyProjection<Point>
+	| OutletResolveFailureProjection<Point>
+	| OutletResolvedProjection<Point>;
+
+/** Lifecycle checkpoint mezi user-observable projection kroky. */
+export type OutletProjectionCheckpoint = () => void;
+
+/** Výchozí resource-free checkpoint čisté projection. */
+function skipOutletProjectionCheckpoint(): void {
+	// Čistá projection bez React ownera nemá další lifecycle gate.
+}
+
+/** Vytvoří bezpečnou atomickou projection chybu se zachovaným cause. */
+function createProjectionError(
+	field: string,
+	cause?: unknown,
+	preserveCause = false,
+): reactAdapterError.ReactAdapterError {
+	return new reactAdapterError.ReactAdapterError(
+		"REACT_RESOLVE_FAILED",
+		"The resolved contribution collection cannot be projected.",
+		preserveCause
+			? { cause, details: { field, phase: "resolve" } }
+			: { details: { field, phase: "resolve" } },
+	);
+}
+
+/** Načte jedno známé projection pole právě jednou a ověří autoritu. */
+function readProjectionProperty(
+	target: object,
+	property: PropertyKey,
+	field: string,
+	checkpoint: OutletProjectionCheckpoint,
+): unknown {
+	let value: unknown;
+	try {
+		value = Reflect.get(target, property, target);
+	} catch (cause: unknown) {
+		throw createProjectionError(field, cause, true);
+	}
+	checkpoint();
+	return value;
+}
+
+/** Ověří optional contribution metadata bez coercion. */
+function requireOptionalProjectionString(value: unknown, field: string): string | undefined {
+	if (value !== undefined && typeof value !== "string") {
+		throw createProjectionError(field);
+	}
+	return value;
+}
+
+/** Vytvoří exact frozen outlet-local placement. */
+function createPlacement(
+	index: number,
+	count: number,
+): contributionComponent.ResolvedContributionPlacement {
+	return Object.freeze({
+		index,
+		count,
+		isFirst: index === 0,
+		isLast: index === count - 1,
+	});
+}
+
+/** Vytvoří bezpečnou implementation error bez raw business hodnoty. */
+function createImplementationError(
+	field: string,
+	cause?: unknown,
+	preserveCause = false,
+): reactAdapterError.ReactAdapterError {
+	return new reactAdapterError.ReactAdapterError(
+		"REACT_POINT_IMPLEMENTATION_INVALID",
+		"The contribution implementation is not supported by the React adapter.",
+		preserveCause
+			? { cause, details: { field, phase: "render" } }
+			: { details: { field, phase: "render" } },
+	);
+}
+
+/** Zachytí jeden Core record a vytvoří frozen public view i render base. */
+function captureMembershipSeedInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	recordValue: unknown,
+	point: Point,
+	context: contribKitCore.ExtensionPointContext<Point>,
+	index: number,
+	count: number,
+	checkpoint: OutletProjectionCheckpoint,
+): {
+	readonly registrationId: string;
+	readonly implementation: unknown;
+	readonly renderState: OutletContributionRenderSeed<Point>;
+} {
+	if (typeof recordValue !== "object" || recordValue === null) {
+		throw createProjectionError(`result.state.contributions[${index}]`);
+	}
+
+	const field = `result.state.contributions[${index}]`;
+	const capturedPoint = readProjectionProperty(recordValue, "point", `${field}.point`, checkpoint);
+	const registrationId = readProjectionProperty(
+		recordValue,
+		"registrationId",
+		`${field}.registrationId`,
+		checkpoint,
+	);
+	const contributionId = readProjectionProperty(
+		recordValue,
+		"contributionId",
+		`${field}.contributionId`,
+		checkpoint,
+	);
+	const contributorId = readProjectionProperty(
+		recordValue,
+		"contributorId",
+		`${field}.contributorId`,
+		checkpoint,
+	);
+	const localName = readProjectionProperty(
+		recordValue,
+		"localName",
+		`${field}.localName`,
+		checkpoint,
+	);
+	const label = readProjectionProperty(recordValue, "label", `${field}.label`, checkpoint);
+	const implementation = readProjectionProperty(
+		recordValue,
+		"implementation",
+		`${field}.implementation`,
+		checkpoint,
+	);
+	const data = readProjectionProperty(recordValue, "data", `${field}.data`, checkpoint);
+
+	if (capturedPoint !== point) {
+		throw createProjectionError(`${field}.point`);
+	}
+	if (typeof registrationId !== "string" || registrationId.length === 0) {
+		throw createProjectionError(`${field}.registrationId`);
+	}
+	if (typeof contributionId !== "string" || contributionId.length === 0) {
+		throw createProjectionError(`${field}.contributionId`);
+	}
+	const capturedContributorId = requireOptionalProjectionString(
+		contributorId,
+		`${field}.contributorId`,
+	);
+	const capturedLocalName = requireOptionalProjectionString(localName, `${field}.localName`);
+	const capturedLabel = requireOptionalProjectionString(label, `${field}.label`);
+	const contribution: contributionComponent.ExtensionContributionView<
+		contribKitCore.ExtensionPointData<Point>
+	> = Object.freeze({
+		contributionId,
+		...(capturedContributorId === undefined ? {} : { contributorId: capturedContributorId }),
+		data: data as contribKitCore.ExtensionPointData<Point>,
+		...(capturedLabel === undefined ? {} : { label: capturedLabel }),
+		...(capturedLocalName === undefined ? {} : { localName: capturedLocalName }),
+	});
+	const placement = createPlacement(index, count);
+	const renderState: OutletContributionRenderSeed<Point> = Object.freeze({
+		context,
+		contribution,
+		placement,
+		point,
+	});
+
+	return Object.freeze({ registrationId, implementation, renderState });
+}
+
+/** Klasifikuje implementation a odliší lifecycle checkpoint failure od accessor failure. */
+function classifyMembershipImplementation(
+	implementation: unknown,
+	checkpoint: OutletProjectionCheckpoint,
+):
+	| { readonly kind: "classified"; readonly value: implementationClassifier.ReactImplementationClassification }
+	| { readonly kind: "failed"; readonly cause: unknown } {
+	let checkpointCause: unknown;
+	let checkpointFailed = false;
+	/** Propaguje lifecycle ztrátu autority namísto jejího překladu na membership failure. */
+	function checkpointClassification(): void {
+		try {
+			checkpoint();
+		} catch (cause: unknown) {
+			checkpointFailed = true;
+			checkpointCause = cause;
+			throw cause;
+		}
+	}
+
+	try {
+		return Object.freeze({
+			kind: "classified" as const,
+			value: implementationClassifier.classifyReactContributionImplementation(
+				implementation,
+				checkpointClassification,
+			),
+		});
+	} catch (cause: unknown) {
+		if (checkpointFailed) {
+			throw checkpointCause;
+		}
+		return Object.freeze({ kind: "failed" as const, cause });
+	}
+}
+
+/** Vytvoří jeden eager, loading nebo failed membership seed bez efektu. */
+function createMembershipSeed<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: ReturnType<typeof captureMembershipSeedInput<Point>>,
+	field: string,
+	checkpoint: OutletProjectionCheckpoint,
+): OutletProjectedMembershipSeed<Point> {
+	const classification = classifyMembershipImplementation(input.implementation, checkpoint);
+	if (classification.kind === "failed") {
+		return Object.freeze({
+			kind: "failed",
+			registrationId: input.registrationId,
+			error: createImplementationError(field, classification.cause, true),
+			renderState: input.renderState,
+		});
+	}
+	if (classification.value.kind === "invalid") {
+		return Object.freeze({
+			kind: "failed",
+			registrationId: input.registrationId,
+			error: createImplementationError(field),
+			renderState: input.renderState,
+		});
+	}
+	if (classification.value.kind === "managedLazy") {
+		return Object.freeze({
+			kind: "loading",
+			registrationId: input.registrationId,
+			load: classification.value.load,
+			renderState: input.renderState,
+		});
+	}
+
+	const component = input.implementation as contributionComponent.ReactContributionComponent<
+		contribKitCore.ExtensionPointContext<Point>,
+		contribKitCore.ExtensionPointData<Point>
+	>;
+	const componentProps: contributionComponent.ExtensionContributionProps<
+		contribKitCore.ExtensionPointContext<Point>,
+		contribKitCore.ExtensionPointData<Point>
+	> = Object.freeze({
+		context: input.renderState.context,
+		contribution: input.renderState.contribution,
+		placement: input.renderState.placement,
+	});
+	const renderState = Object.freeze({
+		...input.renderState,
+		component,
+		componentProps,
+	});
+	return Object.freeze({
+		kind: "ready",
+		registrationId: input.registrationId,
+		renderState,
+	});
+}
+
+/**
+ * Převede jeden frozen hook result na atomický placement a membership candidate.
+ */
+export function projectOutletSnapshot<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	point: Point,
+	context: contribKitCore.ExtensionPointContext<Point>,
+	result: resolvedContributions.UseResolvedContributionsResult<Point>,
+	checkpoint: OutletProjectionCheckpoint = skipOutletProjectionCheckpoint,
+): OutletProjectionSnapshot<Point> {
+	const resultSource = publicInputCapture.requireInputObject(result, "result");
+	const stateValue = readProjectionProperty(resultSource, "state", "result.state", checkpoint);
+	const refreshValue = readProjectionProperty(resultSource, "refresh", "result.refresh", checkpoint);
+	if (typeof refreshValue !== "function") {
+		throw createProjectionError("result.refresh");
+	}
+	if (typeof stateValue !== "object" || stateValue === null) {
+		throw createProjectionError("result.state");
+	}
+
+	const status = readProjectionProperty(stateValue, "status", "result.state.status", checkpoint);
+	if (status === "failed") {
+		const error = readProjectionProperty(
+			stateValue,
+			"error",
+			"result.state.error",
+			checkpoint,
+		) as reactAdapterDiagnostics.ReactAdapterErrorEvent;
+		return Object.freeze({
+			kind: "resolveFailed",
+			renderState: Object.freeze({
+				context,
+				error,
+				point,
+				refresh: refreshValue as () => void,
+			}),
+		});
+	}
+	if (status !== "resolved") {
+		throw createProjectionError("result.state.status");
+	}
+
+	const contributionsValue = readProjectionProperty(
+		stateValue,
+		"contributions",
+		"result.state.contributions",
+		checkpoint,
+	);
+	const emptyReason = readProjectionProperty(
+		stateValue,
+		"emptyReason",
+		"result.state.emptyReason",
+		checkpoint,
+	);
+	if (!Array.isArray(contributionsValue)) {
+		throw createProjectionError("result.state.contributions");
+	}
+	const countValue = readProjectionProperty(
+		contributionsValue,
+		"length",
+		"result.state.contributions.length",
+		checkpoint,
+	);
+	if (typeof countValue !== "number" || !Number.isSafeInteger(countValue) || countValue < 0) {
+		throw createProjectionError("result.state.contributions.length");
+	}
+	if (countValue === 0) {
+		if (emptyReason !== "noRegistrations" && emptyReason !== "excludedByPolicy") {
+			throw createProjectionError("result.state.emptyReason");
+		}
+		return Object.freeze({
+			kind: "empty",
+			renderState: Object.freeze({ context, point, reason: emptyReason }),
+		});
+	}
+	if (emptyReason !== null) {
+		throw createProjectionError("result.state.emptyReason");
+	}
+
+	const memberships: OutletProjectedMembershipSeed<Point>[] = [];
+	const registrationIds = new Set<string>();
+	for (let index = 0; index < countValue; index += 1) {
+		const recordValue = readProjectionProperty(
+			contributionsValue,
+			index,
+			`result.state.contributions[${index}]`,
+			checkpoint,
+		);
+		const captured = captureMembershipSeedInput(
+			recordValue,
+			point,
+			context,
+			index,
+			countValue,
+			checkpoint,
+		);
+		if (registrationIds.has(captured.registrationId)) {
+			throw createProjectionError(`result.state.contributions[${index}].registrationId`);
+		}
+		registrationIds.add(captured.registrationId);
+		memberships.push(createMembershipSeed(
+			captured,
+			`result.state.contributions[${index}].implementation`,
+			checkpoint,
+		));
+	}
+
+	return Object.freeze({
+		kind: "memberships",
+		memberships: Object.freeze(memberships),
+	});
+}