UNPKG

@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
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 { }