@synetics/ui 0.7.0-alpha

package/src/components/organisms/stepper/core/formAdapter.ts

@@ -0,0 +1,66 @@
+/**
+ * Form Adapter Interface
+ * Provides a generic abstraction layer for any form library (RHF, Formik, etc.)
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Generic form state structure
+ */
+export interface FormState {
+    /** Field errors keyed by field name */
+    errors: { [x: string]: any }
+    /** Fields that have been touched/interacted with */
+    touchedFields: { [x: string]: any }
+    /** Fields that have been modified from default values */
+    dirtyFields: { [x: string]: any }
+    /** Whether form is currently validating */
+    isValidating: boolean
+    /** Default/initial form values */
+    defaultValues?: any
+}
+
+/**
+ * Options for setValue operation
+ */
+export interface SetValueOptions {
+    shouldDirty?: boolean
+    shouldTouch?: boolean
+    shouldValidate?: boolean
+}
+
+/**
+ * Form Adapter Interface
+ * Any form library must implement this interface to work with Stepper
+ */
+export interface FormAdapter {
+    // State Access
+    /** Get current form state (errors, touched, dirty, validating, defaults) */
+    getFormState: () => FormState
+
+    // Validation
+    /** Trigger validation for specific fields or all fields */
+    trigger: (fields?: string[]) => Promise<boolean>
+
+    // Value Operations
+    /** Get form values - all values, single field, or multiple fields */
+    getValues: (name?: string | string[]) => any
+
+    /** Set a field value with optional behavior flags */
+    setValue: (name: string, value: any, options?: SetValueOptions) => void
+
+    // Field Operations
+    /** Reset a single field to its default value */
+    resetField: (name: string) => void
+
+    /** Clear errors for specific fields or all fields */
+    clearErrors: (name?: string | string[]) => void
+
+    // Form Operations
+    /** Reset entire form to default values */
+    reset: (values?: any) => void
+
+    /** Set focus to a specific field (optional) */
+    setFocus?: (name: string) => void
+}

package/src/components/organisms/stepper/core/helpers.ts

@@ -0,0 +1,216 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Stepper helpers
+ */
+import { StepperActionsKind } from './actions'
+import { FormAdapter } from './formAdapter'
+import {
+    Action,
+    CustomValidation,
+    IStepAvailabilityTriggeredBy,
+    ITrigger,
+    Payload,
+    PayloadValueTypes,
+    SiblingFinderResult,
+    StepperState
+} from './models'
+
+/** tobe used with dispatch from useReducer in order to provide a payload for the action */
+export const newStepAction = (
+    action: StepperActionsKind,
+    id: number | number[],
+    value: PayloadValueTypes
+): Action => {
+    return {
+        type: action,
+        payload: {
+            stepId: id,
+            value: value
+        } as Payload
+    } as Action
+}
+
+/** To be implemented later */
+export const newCustomValidation = (
+    stepId: number,
+    name: string,
+    method: () => void
+): CustomValidation => {
+    return {
+        stepId,
+        name,
+        method
+    }
+}
+
+// abstractes IStepAvailabilityTriggeredBy object creation
+export const newVisibilitySkipPattern = (id: number, triggeredBy: ITrigger[]) => {
+    return {
+        id: id,
+        triggeredBy: triggeredBy
+    } as IStepAvailabilityTriggeredBy
+}
+
+//  gets the ids list of steps that can be processed.
+// if shouldSkip is found in association with altered fields and expected (to be skip) values then the id is skiped
+export const getAllowedIds = (
+    ids: number[],
+    dirtyFields: string[],
+    shouldSkip: IStepAvailabilityTriggeredBy[],
+    getValues: FormAdapter['getValues']
+    // eslint-disable-next-line sonarjs/cognitive-complexity
+) => {
+    if (dirtyFields.length === 0 || shouldSkip.length === 0) return ids
+
+    const output: number[] = []
+
+    for (const _id of ids) {
+        // find the patterns matching to ID
+        const _patterns = shouldSkip.filter((o) => o.id === _id)
+        if (_patterns.length === 0) {
+            output.push(_id)
+            continue
+        }
+        // verify if some dirty fields were found for
+        for (const _pt of _patterns) {
+            const outValue = []
+            // check if any triggered field has any value
+            for (const triggerField of _pt.triggeredBy) {
+                const value = getValues(triggerField.name)
+                if (
+                    /// if value is has a value and skipIfValues is not waiting 'undefined'
+                    (!value && triggerField.skipIfValue !== undefined) ||
+                    value === triggerField.skipIfValue
+                )
+                    continue
+                // if the value matches the skipIfValue and is not null or undefined
+                outValue.push(value)
+            }
+
+            if (outValue.length < _pt.triggeredBy.length) {
+                continue
+            }
+
+            if (!output?.includes(_id)) {
+                output.push(_id)
+            }
+        }
+    }
+
+    return output
+}
+
+/**  extracts the error object to an ErrorCollection array */
+export const errorToList = (errorObject: { [s: string]: unknown | any }): Error[] => {
+    const errorFields: Error[] = []
+
+    // loop each RHF Error object childs
+    Object.entries(errorObject).forEach((error) => {
+        // get the field name
+        errorFields.push({ name: error[0], message: error[1] ? (error[1]['type'] as string) : '' })
+    })
+
+    return errorFields
+}
+
+/**
+ * It's used by the computeSiblings
+ * this helps to figureout the next available step that should satisfy some rules:
+ * the next step must be available (visible)
+ * the next step must be reachable (not locked)
+ * the current step must be valid in order to move
+ * if not it offsets to the next reachable step which meets the expectations.
+ * @param state the current state
+ * @param fromId the starting point ID
+ * @returns the computed sibling
+ */
+export const findNextAvailableSibling = (
+    state: StepperState,
+    fromId: number
+): SiblingFinderResult | undefined => {
+    if (!state || !state.steps || state.steps.length === 0) return undefined
+
+    const output: SiblingFinderResult = {
+        // define starting point
+        stepId: fromId,
+        step: state.steps.find((o) => o.id === fromId + 1),
+        // navigate from currentState
+        canGo: fromId + 1 <= state.steps.length,
+        // currentState
+        isFirst: false,
+        // currentState
+        isLast: fromId + 1 > state.steps.length
+    }
+    // return last if from id + 1 overflows collection length
+    if (!output.canGo) return output
+
+    // reset cango status so it can be recalculated
+    output.canGo = false
+
+    while (!output.canGo) {
+        output.stepId = output.stepId + 1
+        output.step = state.steps.find((o) => o.id === output.stepId)
+        output.canGo =
+            output.stepId <= state.steps.length &&
+            output.step !== undefined &&
+            !output.step.isLocked &&
+            output.step.isVisible
+        output.isLast = output.stepId > state.steps.length
+
+        // should never happend
+        if (output.stepId > state.steps.length) return output
+    }
+
+    return output
+}
+
+/**
+ * It's used by the computeSiblings
+ * this helps to figureout the previous available step that should satisfy some rules:
+ * the previous step must be available (visible)
+ * the previous step must be reachable (not locked)
+ * the current step must be valid in order to move
+ * if not it offsets to the previous reachable step which meets the expectations.
+ * @param state the current state
+ * @param fromId the starting point ID
+ * @returns the computed sibling
+ */
+export const findPreviousAvailableSibling = (
+    state: StepperState,
+    fromId: number
+): SiblingFinderResult | undefined => {
+    if (!state || !state.steps || state.steps.length === 0) return undefined
+
+    const output: SiblingFinderResult = {
+        // define starting point
+        stepId: fromId,
+        step: state.steps.find((o) => o.id === fromId - 1),
+        // navigate from currentState
+        canGo: fromId - 1 >= 0,
+        // currentState
+        isLast: false,
+        // currentState
+        isFirst: fromId - 1 < 0
+    }
+    // return last if from id + 1 overflows collection length
+    if (!output.canGo) return output
+
+    // reset cango status so it can be recalculated
+    output.canGo = false
+
+    while (!output.canGo) {
+        output.stepId = output.stepId - 1
+        output.step = state.steps.find((o) => o.id === output.stepId)
+        output.canGo =
+            output.stepId >= 0 &&
+            output.step !== undefined &&
+            !output.step.isLocked &&
+            output.step.isVisible
+        output.isFirst = output.stepId < 0
+
+        // should never happend
+        if (output.stepId < 0) return output
+    }
+
+    return output
+}

package/src/components/organisms/stepper/core/models.ts

@@ -0,0 +1,220 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { StepperActionsKind } from './actions'
+
+/** the stepper base configuration options */
+export interface StepperOptions {
+    enableFooterNavigation?: boolean
+    debug?: boolean
+}
+
+/**
+ * Generic form state metadata
+ * Replaces RHFCommon - now form library agnostic
+ */
+export interface FormCommon {
+    errors: { [x: string]: any }
+    touchedFields: { [x: string]: any }
+    dirtyFields: { [x: string]: any }
+}
+
+/**
+ * when default is selected it will validate only from first step to the current one.
+ * when field is selected: KEY MUST BE A STRING
+ * when all is selected: KEY IS OMMITED
+ * when step is selected: KEY MUST BE A NUMBER
+ *  */
+export type ValidationMode = 'default' | 'field' | 'all' | 'step'
+
+export type StepperNavigationRequest = 'back' | 'next' | 'goto' | 'unset'
+
+/** the possible payload values types */
+export type PayloadValueTypes =
+    | string
+    | number
+    | number
+    | boolean
+    | undefined
+    | Error[]
+    | { [x: string]: any }
+    | StepperDefaultValue
+    | FormCommon
+    | StepperNavigationRequest
+    | StepperError
+    | StepperError[]
+    | StepperState
+    | StepperSibling
+    | StepItem
+    | StepItem[]
+    | StepBulkUpdate
+    | StepField
+    | StepField[]
+    | CustomValidation
+    | CustomValidation[]
+    | StepsVisibility
+
+/** the Stepper sibling
+ * this is used as navigation cursor metadata.
+ * it tells stepper about state of sibling steps.
+ * whith it the stepper can let move forward /backward or jump to a step
+ */
+export interface StepperSibling {
+    previousStep?: StepItem
+    currentStep?: StepItem
+    nextStep?: StepItem
+    canGoBack: boolean
+    canGoNext: boolean
+    isLast: boolean
+    isFirst: boolean
+    // to be implemented later
+    direction: 'forward' | 'backward'
+}
+
+/** wrapper error object
+ * with this item we can define in which step the error occurs.
+ */
+export interface StepperError {
+    stepId: number
+    fieldName: string
+    error: Error
+}
+
+/** this is the model to encapsulate all steps that should be set visible or not  */
+export interface StepsVisibility {
+    ids: number[]
+    visible: boolean
+}
+
+/** this is the core stepper state */
+export interface StepperState {
+    // the steps should be registered only once when the form is rendered. this is handled by the Step.tsx component
+    steps: StepItem[]
+    // the current sibling states. Is computed each navigation / validation / jump
+    sibling?: StepperSibling
+    // to be implemented later (can be needed to combine fields)
+    customValidators?: CustomValidation[]
+    // stepper errors (combines validtion and navigation issues)
+    errors: StepperError[]
+    // to be implemented when Backend API will be ready. This will be the output data as is defined by the Bckend Api Contract
+    data: string
+    // count how many times the stepper has been submitted. <=> RHF feature
+    submissionTimes: number
+    // keeps the previous navigated step.
+    previousStepId?: number
+    // this is the current CURSOR navigation ID (StepId)
+    currentStepId?: number
+    // this is RHF Touched Fields
+    touchedFields: string[]
+    // this is RHF Dirty Fields
+    dirtyFields: string[]
+    // the navigation Request next => previous <= goto (number navigationRequestGoto Step Id)
+    navigationRequest: StepperNavigationRequest
+    // if the navigation request is set to goto then this property must be set
+    navigationRequestGoto?: number
+    // tells if the stepper has been loaded (to be implemented if needed itherwise will be removed)
+    loaded: boolean
+    // tells if the stepper is in valid state, this is a deductive notion from validation and Errors
+    isValid: boolean
+    // default commonm value
+    defaultValue: StepperDefaultValue[]
+    // tells if the submit button has been pushed
+    submitRequest: boolean
+    // tells if the stepper is ready (steps and fields available)
+    ready: boolean
+}
+
+/** the Step FIELD artifact will register all the fields that's belong to a step (handled by the person who implements the final form in the custom FORM it self) */
+export interface StepField {
+    name: string
+    // Only when it's needed! This is used when we want to force a component to use a User Friendly Clear Value (i.e. Label than the ID)
+    // please ensure you can set a defaultValue to the targeted component.
+    // In general components uses their default display value and manages their ID's internally.
+    // Be carefull, do not use it as common default value storage. this is for special cases only
+    defaultValue?: string
+}
+
+export interface StepperDefaultValue {
+    name: string
+    value: any
+}
+
+/** The step core state item */
+export interface StepItem {
+    // the UNIQUE id that's must be provided in the Stepper Form definition and also provided to the Custom sub Form       =>   <Step id={YourUniqueID} ><YourCustomForm id={YourUniqueID} ...
+    id: number
+    // this is the Lokalized Step label. Will be used for the breadcrumb step tab AND gathered by the sub Custom form as form TITLE !
+    label: string
+    // tells if the step is valid (computed by validation process)
+    isValid?: boolean
+    // tells if the step is applicable or NOT APPLICABLE at TIME "T" whit the current set of provided data. display a  cross icon if N/A.
+    //  In other words that means that the step has not relevant inpus for the sense of user input data.
+    isVisible: boolean
+    // tells if the step is REACHABLE or not REACHABLE
+    isLocked: boolean
+    // tells tha's the CURRENT DISPLAYED STEP ON SCREEN
+    isActive: boolean
+    // any field has got the focus (RHF)
+    isTouched: boolean
+    // any field has been filled (RHF)
+    isDirty: boolean
+    // the step has been visited at least once and validated (the stepper process needs this in order to know if the fields of the current step should be shown not validated at first sight.)
+    hasBeenValidated: boolean
+    // the fields collection
+    fields: StepField[]
+}
+
+/** the reducer action payload structure */
+export interface Payload {
+    stepId: number | number[]
+    value?: PayloadValueTypes
+}
+
+/** upload data for a STEP that's nearly the same that the step structure with a few more flexibility */
+export interface StepBulkUpdate {
+    id?: number
+    label?: string
+    isValid?: boolean
+    isVisible?: boolean
+    isLocked?: boolean
+    isActive?: boolean
+    fields: StepField[]
+}
+
+/** the action structure */
+export interface Action {
+    type: StepperActionsKind
+    payload: Payload
+}
+
+/** the summary data structure */
+export interface Summary {
+    name: string
+    value: string
+}
+
+/** to be implemented if needed
+ * this will heps to centralize complex validation instead to let user do this in the custom forms itself (can be aborted if not needed.)
+ */
+export interface CustomValidation {
+    stepId: number
+    name: string
+    method: () => void
+}
+
+/** used by the computeSibling process. this is the structure of findNext or findPrevious step... */
+export interface SiblingFinderResult {
+    step?: StepItem
+    isLast: boolean
+    isFirst: boolean
+    canGo: boolean
+    stepId: number
+}
+
+export interface ITrigger {
+    name: string
+    skipIfValue: any
+}
+
+export interface IStepAvailabilityTriggeredBy {
+    id: number
+    triggeredBy: ITrigger[]
+}

package/src/components/organisms/stepper/core/reducer/addCustomValidators.ts

@@ -0,0 +1,14 @@
+import { CustomValidation, Payload, StepperState } from '../models'
+
+/** OCCURS When we add errors to the stepper */
+export const addCustomValidators = (
+    state: StepperState,
+    payload: Payload
+): StepperState | undefined => {
+    const newValidators = payload.value as CustomValidation[]
+
+    return {
+        ...state,
+        customValidators: [...newValidators]
+    } as StepperState
+}

package/src/components/organisms/stepper/core/reducer/addError.ts

@@ -0,0 +1,10 @@
+import { Payload, StepperError, StepperState } from '../models'
+
+/** OCCURS When we add errors to the stepper */
+export const addError = (state: StepperState, payload: Payload): StepperState | undefined => {
+    const newError = payload.value as StepperError
+    return { ...state, errors: [
+        ...state.errors.filter(o => 
+            o.stepId !== newError.stepId && 
+            o.fieldName !== newError.fieldName), newError] } as StepperState
+}

package/src/components/organisms/stepper/core/reducer/addStep.ts

@@ -0,0 +1,7 @@
+import { Payload, StepItem, StepperState } from '../models'
+
+/** OCCURS When we add a step  */
+export const addStep = (state: StepperState, payload: Payload): StepperState | undefined => {
+    const steps = [...state.steps.filter((o) => o.id !== payload.stepId), payload.value as StepItem]
+    return { ...state, steps: steps } as StepperState
+}

package/src/components/organisms/stepper/core/reducer/computeSiblingStatus.ts

@@ -0,0 +1,45 @@
+import { findNextAvailableSibling, findPreviousAvailableSibling } from '../helpers'
+import { StepperSibling, StepperState } from '../models'
+
+/** OCCURS When we recompute the sibling status. */
+export const computeSiblingStatus = (state: StepperState): StepperState | undefined => {
+    if (!state || !state.steps || state.steps.length === 0) return state as StepperState
+    const currentId = state.currentStepId !== undefined ? state.currentStepId : 0
+
+    const currentStep = state.steps.find((o) => o.id === currentId)
+    // we do not want to recalculate sibling if current step is invalid
+    if (!currentStep) return state as StepperState
+    // start point animation
+    const pastId = state.sibling && state.sibling.currentStep ? state.sibling?.currentStep?.id : 0
+    // animatio direction
+    const upcommingId = currentStep ? currentStep.id : 0
+
+    // find available previous and next
+    const findPrevious = findPreviousAvailableSibling(state, currentId)
+    const findNext = findNextAvailableSibling(state, currentId)
+
+    const previousStep = findPrevious?.step
+    const nextStep = findNext?.step
+
+    const canGoBack = findPrevious?.canGo
+    const canGoNext = findNext?.canGo
+
+    const isFirst = findPrevious?.isFirst 
+    const isLast = findNext?.isLast 
+
+    const sibling = {
+        canGoBack,
+        canGoNext,
+        currentStep,
+        nextStep,
+        previousStep,
+        isLast,
+        isFirst,
+        direction: pastId < upcommingId ? 'forward' : 'backward'
+    } as StepperSibling
+
+    return {
+        ...state,
+        sibling: sibling
+    } as StepperState
+}

package/src/components/organisms/stepper/core/reducer/computeValidation.ts

@@ -0,0 +1,61 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+import { StepItem, StepperState } from '../models'
+
+/** OCCURS When we recompute the validation */
+export const computeValidation = (state: StepperState): StepperState | undefined => {
+    if (!state || state.currentStepId === undefined || !state.steps) return state
+
+    // siblings state
+    const newStepsVersion: StepItem[] = [...state.steps]
+
+    const currentStepId = state.currentStepId
+    if (currentStepId === undefined) return state
+
+    const currentStep = newStepsVersion.find((o) => o.id === currentStepId)
+    if (currentStep === undefined) return state
+
+    let requestedStepId = state.navigationRequestGoto
+
+    currentStep.isValid =
+        currentStep.isTouched &&
+        currentStep.isDirty &&
+        state.errors.filter((o) => o.stepId === currentStepId).length === 0
+            ? true
+            : false
+
+    if (
+        requestedStepId !== undefined &&
+        (currentStep.id < requestedStepId || currentStep.id > requestedStepId)
+    ) {
+        currentStep.hasBeenValidated = true
+    }
+
+    // do validation
+    newStepsVersion.forEach((s: StepItem) => {
+        const touched = s.isTouched
+        const dirty = s.isDirty
+        // if requested navigation is located after any step having issues or not filled then set navigation ID to this one instead
+        if (
+            s.isVisible &&
+            requestedStepId !== undefined &&
+            s.id < requestedStepId &&
+            !(dirty && touched)
+        ) {
+            // should take care of this step before moving forward
+            requestedStepId = s.id
+        }
+    })
+
+    const formIsValid = newStepsVersion.filter((o) => o.isVisible).every((o) => o.isValid === true)
+    const sortedNewStepsVersion = [...newStepsVersion].sort((a, b) =>
+        a && b ? a.id - b.id : 1 + 2
+    )
+
+    return {
+        ...state,
+        navigationRequestGoto: requestedStepId,
+        steps: sortedNewStepsVersion,
+        isValid: formIsValid,
+        submitRequest: state.submitRequest ? formIsValid : false
+    } as StepperState
+}