@payfit/unity-components
Version:
90 lines (89 loc) • 4.03 kB
TypeScript
/**
* Navigation policy for one structured-input step.
* @typeParam TStepId - The step's stable ID.
*/
export interface AIStructuredInputNavigationStep<TStepId extends string = string> {
/** Stable ID matching an `AIStructuredInputStep`. */
id: TStepId;
/** Whether an answer action on this active step should advance to the next step. */
autoAdvanceOnAnswer: boolean;
}
/** Options for `useAIStructuredInputNavigation`. */
export interface UseAIStructuredInputNavigationOptions<TSteps extends readonly [
AIStructuredInputNavigationStep,
...AIStructuredInputNavigationStep[]
]> {
/**
* Ordered step IDs and required per-step answer-advance policy. Append new
* steps at the end; removing or reordering existing steps is unsupported.
*/
steps: TSteps;
/**
* The initially active step. Its ID is inferred from `steps`; defaults to
* the first step when omitted.
*/
initialStepId?: TSteps[number]['id'];
}
/** Navigation state and actions returned by `useAIStructuredInputNavigation`. */
export interface UseAIStructuredInputNavigationResult<TStepId extends string> {
/** Current step ID; pass this to `AIStructuredInput.activeStepId`. */
activeStepId: TStepId;
/** Pass this to `AIStructuredInput.onActiveStepChange` to control the root. */
onActiveStepChange: (stepId: string) => void;
/** Changes directly to a known step ID. */
goToStep: (stepId: TStepId) => void;
/** Advances one step, if a next step exists, regardless of answer policy. */
advance: () => void;
/** Moves back one step, when there is a previous step. */
goBack: () => void;
/** Advances only for an answer action on the active step when its policy allows it. */
onAnswer: (stepId: TStepId) => void;
/** Whether the active step is the first step. */
isFirstStep: boolean;
/** Whether the active step is the last step. */
isLastStep: boolean;
/** Whether a next step exists. */
canAdvance: boolean;
/** Whether a previous step exists. */
canGoBack: boolean;
}
/**
* Owns structured-input navigation and per-step answer progression policy.
*
* Pass the returned `activeStepId` and `onActiveStepChange` to
* `AIStructuredInput` to make it controlled. Call `onAnswer(stepId)` after the
* consumer has updated its answer store; it advances only when that step is
* active, has `autoAdvanceOnAnswer: true`, and has a next step. Use `advance`
* for explicit continuation, such as a multi-select Continue action.
*
* This hook never stores, inspects, validates, or submits answer values. Keep
* those in the consumer or a form library such as TanStack Form. Steps may be
* appended at the end while preserving the active ID; removing or reordering
* existing steps is unsupported.
* @typeParam TSteps - A non-empty ordered tuple whose IDs are inferred for the
* returned navigation API and optional `initialStepId`.
* @param options - Ordered step descriptors and optional initial step.
* @returns Controlled navigation state, actions, and derived boundaries.
* @throws {Error} If no steps are configured, `initialStepId` is not in `steps`, or the active step is removed.
* @example
* ```tsx
* const navigation = useAIStructuredInputNavigation({
* steps: [
* { id: 'bonus-type', autoAdvanceOnAnswer: true },
* { id: 'countries', autoAdvanceOnAnswer: false },
* ],
* })
*
* <AIStructuredInput
* activeStepId={navigation.activeStepId}
* onActiveStepChange={navigation.onActiveStepChange}
* >
* </AIStructuredInput>
* ```
* @see {@link UseAIStructuredInputNavigationOptions} for the input contract.
* @see {@link UseAIStructuredInputNavigationResult} for the returned API.
*/
export declare function useAIStructuredInputNavigation<const TSteps extends readonly [
AIStructuredInputNavigationStep,
...AIStructuredInputNavigationStep[]
]>(options: UseAIStructuredInputNavigationOptions<TSteps>): UseAIStructuredInputNavigationResult<TSteps[number]['id']>;