@lorion-org/react 1.0.0-beta.1 → 1.0.0-beta.3

package/src/index.ts

@@ -0,0 +1,225 @@
+import { createContext, createElement, useContext, type ReactElement, type ReactNode } from 'react';
+import {
+  assertKnownDescriptorIds,
+  createDescriptorCatalog,
+  type Descriptor,
+  type DescriptorCatalog,
+} from '@lorion-org/composition-graph';
+import {
+  collectProviderDefaults,
+  collectProviderPreferences,
+  resolveItemProviderSelection,
+  type ProviderPreferenceMap,
+  type ProviderSelectionResolution,
+} from '@lorion-org/provider-selection';
+import type { RuntimeConfigValidationPolicy } from '@lorion-org/runtime-config';
+import { defaultCapabilityRelationDescriptors } from './relations';
+
+export {
+  createCapabilityCompositionPolicy,
+  defaultCapabilityRelationDescriptors,
+  defaultCapabilityResolutionRelations,
+} from './relations';
+export * from './runtime-config';
+
+export type CapabilityManifest = Descriptor & {
+  defaultFor?: string | string[];
+  description?: string;
+  providerPreferences?: ProviderPreferenceMap;
+  runtimeConfig?: RuntimeConfigValidationPolicy;
+};
+
+export type ExtensionPoint<T> = {
+  id: string;
+  readonly value?: T;
+};
+
+export type CapabilityContribution<T = unknown> = {
+  extensionPoint: ExtensionPoint<T>;
+  values: readonly T[];
+};
+
+export type RuntimeCapability = {
+  id: string;
+  manifest: CapabilityManifest;
+  contributions?: readonly CapabilityContribution[];
+};
+
+export type CapabilityRuntime = {
+  capabilities: readonly RuntimeCapability[];
+  catalog: DescriptorCatalog;
+  getContributions: <T>(extensionPoint: ExtensionPoint<T>) => T[];
+};
+
+export type ContributionContract<T> = {
+  define: (values: readonly T[]) => CapabilityContribution<T>;
+  extensionPoint: ExtensionPoint<T>;
+  get: (runtime: CapabilityRuntime) => T[];
+  use: () => T[];
+};
+
+export function defineExtensionPoint<T>(id: string): ExtensionPoint<T> {
+  return { id };
+}
+
+export function defineContribution<T>(
+  extensionPoint: ExtensionPoint<T>,
+  values: readonly T[],
+): CapabilityContribution<T> {
+  return { extensionPoint, values };
+}
+
+export function createContributionContract<T>(id: string): ContributionContract<T> {
+  const extensionPoint = defineExtensionPoint<T>(id);
+
+  return {
+    extensionPoint,
+    define: (values) => defineContribution(extensionPoint, values),
+    get: (runtime) => runtime.getContributions(extensionPoint),
+    use: () => useCapabilityRuntime().getContributions(extensionPoint),
+  };
+}
+
+export type CapabilityProviderSelectionOptions = {
+  configuredProviders?: ProviderPreferenceMap;
+  fallbackProviders?: ProviderPreferenceMap;
+  selectedProviders?: ProviderPreferenceMap;
+};
+
+export function getCapabilityProviderSelection(
+  runtime: CapabilityRuntime,
+  options: CapabilityProviderSelectionOptions = {},
+): ProviderSelectionResolution {
+  const descriptors = runtime.catalog.getAllDescriptors();
+  const descriptorPreferences = collectProviderPreferences({
+    items: descriptors,
+    getProviderPreferences: (descriptor) => descriptor.providerPreferences,
+  });
+  const providerDefaults = collectProviderDefaults({
+    items: descriptors,
+    getDefaultFor: (descriptor) => descriptor.defaultFor,
+    getProviderId: (descriptor) => descriptor.id,
+  });
+  const configuredProviders = options.configuredProviders ?? {};
+  const selectedProviders = options.selectedProviders ?? {};
+  const fallbackProviders = {
+    ...providerDefaults,
+    ...descriptorPreferences,
+    ...(options.fallbackProviders ?? {}),
+  };
+  const resolution = resolveItemProviderSelection({
+    items: descriptors,
+    getCapabilityId: (descriptor) => descriptor.providesFor,
+    getProviderId: (descriptor) => descriptor.id,
+    configuredProviders,
+    fallbackProviders,
+    selectedProviders,
+  });
+
+  return {
+    excludedProviderIds: resolution.excludedProviderIds,
+    mismatches: resolution.mismatches,
+    selections: resolution.selections,
+  };
+}
+
+export function defineCapability(capability: RuntimeCapability): RuntimeCapability {
+  if (capability.id !== capability.manifest.id) {
+    throw new Error(
+      `Capability "${capability.id}" must match capability.json id "${capability.manifest.id}".`,
+    );
+  }
+
+  return capability;
+}
+
+export function createCapabilityRuntime(
+  capabilities: readonly RuntimeCapability[],
+): CapabilityRuntime {
+  const enabledCapabilities = capabilities.filter(
+    (capability) => capability.manifest.disabled !== true,
+  );
+  const catalog = createCapabilityCatalog(enabledCapabilities);
+
+  assertUniqueCapabilities(enabledCapabilities);
+  assertKnownCapabilityDependencies(enabledCapabilities, catalog);
+
+  const contributions = collectContributions(enabledCapabilities);
+
+  return {
+    capabilities: Object.freeze([...enabledCapabilities]),
+    catalog,
+    getContributions: <T>(extensionPoint: ExtensionPoint<T>) =>
+      [...(contributions.get(extensionPoint.id) ?? [])] as T[],
+  };
+}
+
+const CapabilityRuntimeContext = createContext<CapabilityRuntime | null>(null);
+
+export type CapabilityRuntimeProviderProps = {
+  children: ReactNode;
+  runtime: CapabilityRuntime;
+};
+
+export function CapabilityRuntimeProvider({
+  children,
+  runtime,
+}: CapabilityRuntimeProviderProps): ReactElement {
+  return createElement(CapabilityRuntimeContext.Provider, { value: runtime }, children);
+}
+
+export function useCapabilityRuntime(): CapabilityRuntime {
+  const runtime = useContext(CapabilityRuntimeContext);
+
+  if (!runtime) {
+    throw new Error('useCapabilityRuntime must be used inside CapabilityRuntimeProvider.');
+  }
+
+  return runtime;
+}
+
+function assertUniqueCapabilities(capabilities: readonly RuntimeCapability[]): void {
+  const seen = new Set<string>();
+
+  for (const capability of capabilities) {
+    if (seen.has(capability.id)) {
+      throw new Error(`Duplicate capability id "${capability.id}".`);
+    }
+
+    seen.add(capability.id);
+  }
+}
+
+function assertKnownCapabilityDependencies(
+  capabilities: readonly RuntimeCapability[],
+  catalog: DescriptorCatalog,
+): void {
+  for (const capability of capabilities) {
+    assertKnownDescriptorIds(
+      catalog.getDescriptorMap(),
+      Object.keys(capability.manifest.dependencies ?? {}),
+      `capability "${capability.id}" dependencies`,
+    );
+  }
+}
+
+function collectContributions(capabilities: readonly RuntimeCapability[]): Map<string, unknown[]> {
+  const contributions = new Map<string, unknown[]>();
+
+  for (const capability of capabilities) {
+    for (const contribution of capability.contributions ?? []) {
+      const bucket = contributions.get(contribution.extensionPoint.id) ?? [];
+      bucket.push(...contribution.values);
+      contributions.set(contribution.extensionPoint.id, bucket);
+    }
+  }
+
+  return contributions;
+}
+
+function createCapabilityCatalog(capabilities: readonly RuntimeCapability[]): DescriptorCatalog {
+  return createDescriptorCatalog({
+    descriptors: capabilities.map((capability) => capability.manifest),
+    relationDescriptors: defaultCapabilityRelationDescriptors,
+  });
+}

package/src/relations.ts

@@ -0,0 +1,8 @@
+// The capability relations and composition policy are owned by
+// @lorion-org/descriptor-selection. They are re-exported here under the React
+// adapter's public names for backward compatibility; no logic is duplicated.
+export {
+  providerRelationDescriptors as defaultCapabilityRelationDescriptors,
+  descriptorSelectionPolicy as createCapabilityCompositionPolicy,
+  defaultResolutionRelations as defaultCapabilityResolutionRelations,
+} from '@lorion-org/descriptor-selection';

package/src/runtime-config.ts

@@ -0,0 +1,63 @@
+import { createContext, createElement, useContext, type ReactElement, type ReactNode } from 'react';
+import type { RuntimeConfigSection } from '@lorion-org/runtime-config';
+
+export type CapabilityRuntimeConfig = {
+  public: Record<string, RuntimeConfigSection>;
+};
+
+export type CapabilityRuntimeConfigFragment<T extends RuntimeConfigSection = RuntimeConfigSection> =
+  {
+    public: T;
+  };
+
+export type CapabilityRuntimeConfigProviderProps = {
+  children: ReactNode;
+  runtimeConfig: CapabilityRuntimeConfig;
+};
+
+const emptyRuntimeConfig: CapabilityRuntimeConfig = Object.freeze({ public: Object.freeze({}) });
+const CapabilityRuntimeConfigContext = createContext<CapabilityRuntimeConfig>(emptyRuntimeConfig);
+
+export function CapabilityRuntimeConfigProvider({
+  children,
+  runtimeConfig,
+}: CapabilityRuntimeConfigProviderProps): ReactElement {
+  return createElement(CapabilityRuntimeConfigContext.Provider, { value: runtimeConfig }, children);
+}
+
+export function useCapabilityRuntimeConfigScope<
+  T extends RuntimeConfigSection = RuntimeConfigSection,
+>(capabilityId: string): T {
+  return getCapabilityRuntimeConfigScope<T>(useCapabilityRuntimeConfigRoot(), capabilityId);
+}
+
+export function useCapabilityRuntimeConfig<T extends RuntimeConfigSection = RuntimeConfigSection>(
+  capabilityId: string,
+): CapabilityRuntimeConfigFragment<T> {
+  return getCapabilityRuntimeConfig<T>(useCapabilityRuntimeConfigRoot(), capabilityId);
+}
+
+export function useCapabilityRuntimeConfigRoot(): CapabilityRuntimeConfig {
+  return useContext(CapabilityRuntimeConfigContext);
+}
+
+export function getCapabilityRuntimeConfigScope<
+  T extends RuntimeConfigSection = RuntimeConfigSection,
+>(runtimeConfig: CapabilityRuntimeConfig, capabilityId: string): T {
+  const publicConfig = runtimeConfig.public[capabilityId];
+
+  return (
+    publicConfig && typeof publicConfig === 'object' && !Array.isArray(publicConfig)
+      ? publicConfig
+      : {}
+  ) as T;
+}
+
+export function getCapabilityRuntimeConfig<T extends RuntimeConfigSection = RuntimeConfigSection>(
+  runtimeConfig: CapabilityRuntimeConfig,
+  capabilityId: string,
+): CapabilityRuntimeConfigFragment<T> {
+  return {
+    public: getCapabilityRuntimeConfigScope<T>(runtimeConfig, capabilityId),
+  };
+}