@viamedici-spc/configurator-react
Version:
React library to build configurator web applications based on the Viamedici Headless Configuration Engine (HCE).
526 lines (469 loc) • 25.6 kB
TypeScript
import { Atom } from 'jotai';
import { AtomFamily } from 'jotai/vanilla/utils/atomFamily';
import { Attribute } from '@viamedici-spc/configurator-ts';
import { BooleanAttribute } from '@viamedici-spc/configurator-ts';
import { ChoiceAttribute } from '@viamedici-spc/configurator-ts';
import { ChoiceValue } from '@viamedici-spc/configurator-ts';
import { ChoiceValueDecisionState } from '@viamedici-spc/configurator-ts';
import { ChoiceValueId } from '@viamedici-spc/configurator-ts';
import { CollectedDecision } from '@viamedici-spc/configurator-ts';
import { CollectedExplicitDecision } from '@viamedici-spc/configurator-ts';
import { CollectedImplicitDecision } from '@viamedici-spc/configurator-ts';
import { ComponentAttribute } from '@viamedici-spc/configurator-ts';
import { ComponentDecisionState } from '@viamedici-spc/configurator-ts';
import { Configuration as Configuration_2 } from '@viamedici-spc/configurator-ts';
import { ConfiguratorError } from '@viamedici-spc/configurator-ts';
import { ConstraintsExplainAnswer } from '@viamedici-spc/configurator-ts';
import { createStore } from 'jotai';
import { DecisionKind } from '@viamedici-spc/configurator-ts';
import { DecisionsExplainAnswer } from '@viamedici-spc/configurator-ts';
import { ExplainQuestion } from '@viamedici-spc/configurator-ts';
import { ExplainQuestionParam as ExplainQuestionParam_2 } from '@viamedici-spc/configurator-ts';
import { ExplainSolution } from '@viamedici-spc/configurator-ts';
import { ExplicitDecision } from '@viamedici-spc/configurator-ts';
import { FullExplainAnswer } from '@viamedici-spc/configurator-ts';
import { GlobalAttributeId } from '@viamedici-spc/configurator-ts';
import { GlobalAttributeIdKey } from '@viamedici-spc/configurator-ts';
import { JSX as JSX_2 } from 'react/jsx-runtime';
import { MakeManyDecisionsMode } from '@viamedici-spc/configurator-ts';
import { MakeManyDecisionsResult } from '@viamedici-spc/configurator-ts';
import { NumericAttribute } from '@viamedici-spc/configurator-ts';
import { PropsWithChildren } from 'react';
import { SessionContext } from '@viamedici-spc/configurator-ts';
import { StoredConfiguration } from '@viamedici-spc/configurator-ts';
import { WhyIsAttributeNotSatisfied } from '@viamedici-spc/configurator-ts';
import { WhyIsBooleanStateNotPossible } from '@viamedici-spc/configurator-ts';
import { WhyIsChoiceValueStateNotPossible } from '@viamedici-spc/configurator-ts';
import { WhyIsComponentStateNotPossible } from '@viamedici-spc/configurator-ts';
import { WhyIsNumericStateNotPossible } from '@viamedici-spc/configurator-ts';
import { WhyIsStateNotPossible } from '@viamedici-spc/configurator-ts';
export declare function Configuration(props: PropsWithChildren<ConfigurationProps>): JSX_2.Element;
export declare type ConfigurationInitialization = {
/**
* Gets whether the Configuration is currently initializing.
*/
readonly isInitializing: boolean;
readonly error?: ConfiguratorErrorWithRetry;
};
export declare type ConfigurationProps = {
/**
* The SessionContext that should be used to create the session. Every time the SessionContext change, a new Session is created and all decisions are tried to restore.
* @remarks A change to the SessionContext is detected using referentially equality. Consider using {@link useMemo} or {@link useRef} to keep the SessionContext unchanged during rendering.
*/
sessionContext: SessionContext;
/**
* An optional Jotai store where all Atoms will be stored in. Defaults to the result of {@link getDefaultStore()}.
*/
jotaiStore?: ReturnType<typeof createStore>;
};
export declare type ConfigurationUninitialized = "ConfigurationUninitialized";
export declare const ConfigurationUninitialized: ConfigurationUninitialized;
export declare type ConfigurationUpdating = {
/**
* Gets whether the Configuration is currently updating.
*/
readonly isUpdating: boolean;
readonly error?: ConfiguratorErrorWithRetry;
};
/**
* Represents an error that occurred during initializing or updating a Session.
*/
export declare type ConfiguratorErrorWithRetry = ConfiguratorError & {
/**
* Retry the failed operation.
*/
readonly retry?: () => void;
};
declare type ExplainQuestionParam<T extends WhyIsStateNotPossible> = SimplifiedExplainQuestion<WhyIsAttributeNotSatisfied> | SimplifiedExplainQuestion<T>;
/**
* Represents an Atom which is guarded against access while the Configuration is not fully initialized.
*/
export declare type GuardedAtom<Value> = Atom<Value | ConfigurationUninitialized>;
/**
* A type guard that checks if the given value is initialized.
*
* This type guard is useful for narrowing a union type containing {@link ConfigurationUninitialized}
* to only include the initialized type `T`.
*
* @returns `true` if the value is of type `T`.
*/
export declare const isConfigurationInitialized: <T>(v: T | ConfigurationUninitialized) => v is T;
declare type SimplifiedExplainQuestion<T extends ExplainQuestion> = Omit<T, "attributeId" | "subject">;
declare type UseAttributeExplainResult<T extends WhyIsStateNotPossible> = {
explain: {
(question: ExplainQuestionParam<T>, answerType: "decisions"): Promise<DecisionsExplainAnswer>;
(question: ExplainQuestionParam<T>, answerType: "constraints"): Promise<ConstraintsExplainAnswer>;
(question: ExplainQuestionParam<T>, answerType: "full"): Promise<FullExplainAnswer>;
};
applySolution(solution: ExplainSolution): Promise<MakeManyDecisionsResult>;
};
/**
* Retrieves all existing attributes.
* @param attributes Set to "all" to retrieve all existing attributes.
* @remarks Will suspend until the Configuration is fully initialized.
*/
export declare function useAttributes(attributes: "all"): ReadonlyArray<Attribute>;
/**
* Retrieves all existing attributes.
* @param attributes Set to "all" to retrieve all existing attributes.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useAttributes(attributes: "all", suspend: false): ReadonlyArray<Attribute> | ConfigurationUninitialized;
/**
* Retrieves the requested attributes.
* @param attributes The attributes to return.
* @param filterMissingAttributes Whether to ignore that requested attributes are missing. Missing attributes will be filtered out of the result.
* @returns The requested attributes in the order of the {@link attributes} parameter.
* @remarks Will suspend until the Configuration is fully initialized.
*/
export declare function useAttributes(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: true): ReadonlyArray<Attribute>;
/**
* Retrieves the requested attributes.
* @param attributes The attributes to return.
* @param filterMissingAttributes Whether to ignore that requested attributes are missing. Missing attributes appear as undefined in the result.
* @returns The requested attributes in the order of the {@link attributes} parameter.
* @remarks Will suspend until the Configuration is fully initialized.
*/
export declare function useAttributes(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: false): ReadonlyArray<Attribute | undefined>;
/**
* Retrieves the requested attributes.
* @param attributes The attributes to return.
* @param filterMissingAttributes Whether to ignore that requested attributes are missing. Missing attributes will be filtered out of the result.
* @returns The requested attributes in the order of the {@link attributes} parameter.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useAttributes(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: true, suspend: false): ReadonlyArray<Attribute | undefined> | ConfigurationUninitialized;
/**
* Retrieves the requested attributes.
* @param attributes The attributes to return.
* @param filterMissingAttributes Whether to ignore that requested attributes are missing. Missing attributes appear as undefined in the result.
* @returns The requested attributes in the order of the {@link attributes} parameter.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useAttributes(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: false, suspend: false): ReadonlyArray<Attribute> | ConfigurationUninitialized;
export declare const useBooleanAttribute: {
/**
* Gets the requested boolean attribute with specific commands and queries.
* @param attributeIdOrKey The id of the boolean attribute.
* @returns Undefined if attribute doesn't exist, or it is not a boolean attribute.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey): UseBooleanAttributeResult | undefined;
/**
* Gets the requested boolean attribute with specific commands and queries.
* @param attributeIdOrKey The id of the boolean attribute.
* @param suspend Whether to disable the Suspense API.
* @returns Undefined if attribute doesn't exist, or it is not a boolean attribute.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey, suspend: false): UseBooleanAttributeResult | undefined | ConfigurationUninitialized;
};
export declare type UseBooleanAttributeResult = UseAttributeExplainResult<WhyIsBooleanStateNotPossible> & {
attribute: BooleanAttribute;
makeDecision: (state: boolean | null | undefined) => Promise<void>;
isMandatory: () => boolean;
};
export declare const useChoiceAttribute: {
/**
* Gets the requested choice attribute with specific commands and queries.
* @param attributeIdOrKey The id or key of the choice attribute.
* @returns Undefined if attribute doesn't exist, or it is not a choice attribute.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey): UseChoiceAttributeResult | undefined;
/**
* Gets the requested choice attribute with specific commands and queries.
* @param attributeIdOrKey The id or key of the choice attribute.
* @param suspend Whether to disable the Suspense API.
* @returns Undefined if attribute doesn't exist, or it is not a choice attribute.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey, suspend: false): UseChoiceAttributeResult | undefined | ConfigurationUninitialized;
};
export declare type UseChoiceAttributeResult = UseAttributeExplainResult<WhyIsChoiceValueStateNotPossible> & {
attribute: ChoiceAttribute;
makeDecision: (choiceValueId: ChoiceValueId, state: ChoiceValueDecisionState | null | undefined) => Promise<void>;
clearDecisions: () => Promise<void>;
isMultiSelect: () => boolean;
isMandatory: () => boolean;
getAllowedChoiceValues: () => ReadonlyArray<ChoiceValue>;
getBlockedChoiceValues: () => ReadonlyArray<ChoiceValue>;
getIncludedChoiceValues: () => ReadonlyArray<ChoiceValue>;
isChoiceValueAllowed: (choiceValue: ChoiceValue) => boolean;
isChoiceValueBlocked: (choiceValue: ChoiceValue) => boolean;
};
export declare const useComponentAttribute: {
/**
* Gets the requested component attribute with specific commands and queries.
* @param attributeIdOrKey The id of the component attribute.
* @returns Undefined if attribute doesn't exist, or it is not a component attribute.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey): UseComponentAttributeResult | undefined;
/**
* Gets the requested component attribute with specific commands and queries.
* @param attributeIdOrKey The id of the component attribute.
* @param suspend Whether to disable the Suspense API.
* @returns Undefined if attribute doesn't exist, or it is not a component attribute.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey, suspend: false): UseComponentAttributeResult | undefined | ConfigurationUninitialized;
};
export declare type UseComponentAttributeResult = UseAttributeExplainResult<WhyIsComponentStateNotPossible> & {
attribute: ComponentAttribute;
makeDecision: (state: ComponentDecisionState | null | undefined) => Promise<void>;
isMandatory: () => boolean;
};
export declare const useConfiguration: {
/**
* Gets the current Configuration state.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(): Configuration_2;
/**
* Gets the current Configuration state.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): Configuration_2 | ConfigurationUninitialized;
};
/**
* Gets the initialization information for the Configuration.
*/
export declare function useConfigurationInitialization(): ConfigurationInitialization;
export declare const useConfigurationReset: {
/**
* Gets whether the Configuration can be reset and a command to actually reset the Configuration to its initial state.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(): UseConfigurationResetResult;
/**
* Gets whether the Configuration can be reset and a command to actually reset the Configuration to its initial state.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseConfigurationResetResult | ConfigurationUninitialized;
};
export declare type UseConfigurationResetResult = {
canResetConfiguration: boolean;
resetConfiguration: () => Promise<void>;
};
export declare const useConfigurationSatisfaction: {
/**
* Gets the Configuration satisfaction state and allows to explain an unsatisfied state.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): UseConfigurationSatisfactionResult;
/**
* Gets the Configuration satisfaction state and allows to explain an unsatisfied state.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseConfigurationSatisfactionResult | ConfigurationUninitialized;
};
export declare type UseConfigurationSatisfactionResult = {
isSatisfied: boolean;
explain: {
(answerType: "decisions"): Promise<DecisionsExplainAnswer>;
(answerType: "constraints"): Promise<ConstraintsExplainAnswer>;
(answerType: "full"): Promise<FullExplainAnswer>;
};
};
export declare const useConfigurationStoring: {
/**
* Gets commands to store and restore a Configuration.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): UseConfigurationStoringResult;
/**
* Gets commands to store and restore a Configuration.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseConfigurationStoringResult | ConfigurationUninitialized;
};
export declare type UseConfigurationStoringResult = {
storeConfiguration: () => Promise<StoredConfiguration>;
restoreConfiguration: (storedConfiguration: StoredConfiguration, mode: MakeManyDecisionsMode) => Promise<MakeManyDecisionsResult>;
};
/**
* Gets the updating information for the Configuration.
*/
export declare function useConfigurationUpdating(): ConfigurationUpdating;
export declare const useConfiguratorStore: () => ReturnType<typeof createStore>;
export declare const useDecisionQueries: {
/**
* Gets commands to query the decisions of a Configuration.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): UseDecisionQueriesResult;
/**
* Gets commands to query the decisions of a Configuration.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseDecisionQueriesResult | ConfigurationUninitialized;
};
export declare type UseDecisionQueriesResult = {
getDecisions(kind: DecisionKind.Explicit): ReadonlyArray<CollectedExplicitDecision>;
getDecisions(kind: DecisionKind.Explicit, queue: true): Promise<ReadonlyArray<CollectedExplicitDecision>>;
getDecisions(kind: DecisionKind.Implicit): ReadonlyArray<CollectedImplicitDecision>;
getDecisions(kind: DecisionKind.Implicit, queue: true): Promise<ReadonlyArray<CollectedImplicitDecision>>;
getDecisions(): ReadonlyArray<CollectedDecision>;
getDecisions(queue: true): Promise<ReadonlyArray<CollectedDecision>>;
};
/**
* Gets all implicit and explicit, non-optimistic decisions of the current Configuration.
* @remarks Will suspend until the configuration is fully initialized.
*/
export declare function useDecisions(): ReadonlyArray<CollectedDecision>;
/**
* Gets all implicit and explicit, non-optimistic decisions of the current Configuration.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useDecisions(suspend: false): ReadonlyArray<CollectedDecision> | ConfigurationUninitialized;
/**
* Gets all explicit non-optimistic decisions of the current Configuration.
* @param kind The kind of decisions that should be returned.
* @remarks Will suspend until the configuration is fully initialized.
*/
export declare function useDecisions(kind: DecisionKind.Explicit): ReadonlyArray<CollectedExplicitDecision>;
/**
* Gets all explicit non-optimistic decisions of the current Configuration.
* @param kind The kind of decisions that should be returned.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useDecisions(kind: DecisionKind.Explicit, suspend: false): ReadonlyArray<CollectedExplicitDecision> | ConfigurationUninitialized;
/**
* Gets all implicit non-optimistic decisions of the current Configuration.
* @param kind The kind of decisions that should be returned.
* @remarks Will suspend until the configuration is fully initialized.
*/
export declare function useDecisions(kind: DecisionKind.Implicit): ReadonlyArray<CollectedImplicitDecision>;
/**
* Gets all implicit non-optimistic decisions of the current Configuration.
* @param kind The kind of decisions that should be returned.
* @param suspend Whether to disable the Suspense API.
*/
export declare function useDecisions(kind: DecisionKind.Implicit, suspend: false): ReadonlyArray<CollectedImplicitDecision> | ConfigurationUninitialized;
export declare const useExplain: {
/**
* Gets commands for explaining circumstances.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(): UseExplainResult;
/**
* Gets commands for explaining circumstances.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseExplainResult | ConfigurationUninitialized;
};
export declare type UseExplainResult = {
explain(question: ExplainQuestionParam_2, answerType: "decisions"): Promise<DecisionsExplainAnswer>;
explain(question: ExplainQuestionParam_2, answerType: "constraints"): Promise<ConstraintsExplainAnswer>;
explain(question: ExplainQuestionParam_2, answerType: "full"): Promise<FullExplainAnswer>;
applySolution(solution: ExplainSolution): Promise<MakeManyDecisionsResult>;
};
/**
* Gets all Jotai based atoms and atom families of the Configuration session.
* They can be used to build more advanced reactive pipelines with Jotai.
*/
export declare function useJotaiAtoms(): UseJotaiAtomsResult;
export declare type UseJotaiAtomsResult = {
createAttributesAtom: {
(attributes: "all"): GuardedAtom<ReadonlyArray<Attribute>>;
(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: true): GuardedAtom<ReadonlyArray<Attribute>>;
(attributes: ReadonlyArray<GlobalAttributeId | GlobalAttributeIdKey>, filterMissingAttributes: false): GuardedAtom<ReadonlyArray<Attribute | undefined>>;
};
getConfigurationInitializationAtom: Atom<ConfigurationInitialization>;
getConfigurationUpdatingAtom: Atom<ConfigurationUpdating>;
getChoiceAttributeAtomFamily: AtomFamily<GlobalAttributeIdKey, GuardedAtom<UseChoiceAttributeResult | undefined>>;
getNumericAttributeAtomFamily: AtomFamily<GlobalAttributeIdKey, GuardedAtom<UseNumericAttributeResult | undefined>>;
getBooleanAttributeAtomFamily: AtomFamily<GlobalAttributeIdKey, GuardedAtom<UseBooleanAttributeResult | undefined>>;
getComponentAttributeAtomFamily: AtomFamily<GlobalAttributeIdKey, GuardedAtom<UseComponentAttributeResult | undefined>>;
getConfigurationAtom: GuardedAtom<Configuration_2>;
getConfigurationStoringAtom: GuardedAtom<UseConfigurationStoringResult>;
getConfigurationSatisfactionAtom: GuardedAtom<UseConfigurationSatisfactionResult>;
getMakeDecisionAtom: GuardedAtom<UseMakeDecisionResult>;
getDecisionQueriesAtom: GuardedAtom<UseDecisionQueriesResult>;
getConfigurationResetAtom: GuardedAtom<UseConfigurationResetResult>;
getSessionReinitializationAtom: GuardedAtom<UseSessionReinitializationResult>;
getExplainAtom: GuardedAtom<UseExplainResult>;
getTaskSchedulingAtom: GuardedAtom<UseTaskSchedulingResult>;
getStoredConfigurationAtom: GuardedAtom<StoredConfiguration>;
getDecisionsAtom: GuardedAtom<ReadonlyArray<CollectedDecision>>;
getExplicitDecisionsAtom: GuardedAtom<ReadonlyArray<CollectedExplicitDecision>>;
getImplicitDecisionsAtom: GuardedAtom<NonNullable<ReadonlyArray<CollectedImplicitDecision>>>;
};
export declare const useMakeDecision: {
/**
* Gets commands for making one or many decisions.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(): UseMakeDecisionResult;
/**
* Gets commands for making one or many decisions.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseMakeDecisionResult | ConfigurationUninitialized;
};
export declare type UseMakeDecisionResult = {
makeDecision: (decision: ExplicitDecision) => Promise<void>;
makeManyDecisions: (decisions: ReadonlyArray<ExplicitDecision>, mode: MakeManyDecisionsMode) => Promise<MakeManyDecisionsResult>;
};
export declare const useNumericAttribute: {
/**
* Gets the requested numeric attribute with specific commands and queries.
* @param attributeIdOrKey The id or key of the numeric attribute.
* @returns Undefined if attribute doesn't exist, or it is not a numeric attribute.
* @remarks Will suspend until the Configuration is fully initialized.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey): UseNumericAttributeResult | undefined;
/**
* Gets the requested numeric attribute with specific commands and queries.
* @param attributeIdOrKey The id or key of the numeric attribute.
* @param suspend Whether to disable the Suspense API.
* @returns Undefined if attribute doesn't exist, or it is not a numeric attribute.
*/
(attributeIdOrKey: GlobalAttributeId | GlobalAttributeIdKey, suspend: false): UseNumericAttributeResult | undefined | ConfigurationUninitialized;
};
export declare type UseNumericAttributeResult = UseAttributeExplainResult<WhyIsNumericStateNotPossible> & {
attribute: NumericAttribute;
makeDecision: (state: number | null | undefined) => Promise<void>;
isMandatory: () => boolean;
};
export declare const useSessionReinitialization: {
/**
* Gets a command to reinitialize the session by creating a new session and attempts to migrate all existing decisions.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): UseSessionReinitializationResult;
/**
* Gets a command to reinitialize the session by creating a new session and attempts to migrate all existing decisions.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseSessionReinitializationResult | ConfigurationUninitialized;
};
export declare type UseSessionReinitializationResult = {
reinitializeSession: () => Promise<void>;
};
export declare const useStoredConfiguration: {
/**
* Gets the current non-optimistic Configuration state.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): StoredConfiguration;
/**
* Gets the current non-optimistic Configuration state.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): StoredConfiguration | ConfigurationUninitialized;
};
export declare const useTaskScheduling: {
/**
* Gets a command to schedule tasks.
* @remarks Will suspend until the configuration is fully initialized.
*/
(): UseTaskSchedulingResult;
/**
* Gets a command to schedule tasks.
* @param suspend Whether to disable the Suspense API.
*/
(suspend: false): UseTaskSchedulingResult | ConfigurationUninitialized;
};
export declare type UseTaskSchedulingResult = {
scheduleTask: (signal?: AbortSignal | null) => Promise<void>;
};
export { }