@inseefr/lunatic 3.4.10-rc.0 → 3.4.10

package/src/components/shared/HOC/slottableComponent.tsx

@@ -45,7 +45,7 @@ import type { MarkdownLink } from '../MDLabel/MarkdownLink';
 import type { Accordion } from '../../Accordion/Accordion';
 
 /**
- * Contains the type of every customizable component
+ * Contain the type of every customizable components.
  */
 export type LunaticSlotComponents = {
 	// Components
@@ -130,9 +130,9 @@ export const SlotsProvider = ({
 };
 
 /**
- * Create a replaceable version of a component
+ * Create a replaceable version of a component.
  *
- * The component can be replaced using the "slots" props on <LunaticComponents>
+ * The component can be replaced through the `slots` props on `LunaticComponents`.
  */
 export function slottableComponent<T>(
 	name: keyof LunaticSlotComponents,

package/src/components/shared/Radio/RadioOption.spec.tsx

@@ -25,6 +25,61 @@ describe('RadioOption', () => {
 		expect(onClickMock).toHaveBeenCalled();
 	});
 
+	it('does not allow to uncheck modality if checkboxStyle is not defined', () => {
+		const onClickMock = vi.fn();
+		render(
+			<RadioOption
+				id="radio-option"
+				label="Test Option"
+				onCheck={onClickMock}
+				onUncheck={onClickMock}
+				checked
+			/>
+		);
+
+		const option = screen.getByRole('radio');
+		fireEvent.click(option);
+		expect(onClickMock).not.toHaveBeenCalled();
+	});
+
+	it('does not allow to uncheck modality if checkboxStyle is false', () => {
+		const onClickMock = vi.fn();
+
+		render(
+			<RadioOption
+				id="radio-option"
+				label="Test Option"
+				onCheck={onClickMock}
+				onUncheck={onClickMock}
+				checkboxStyle={false}
+				checked
+			/>
+		);
+
+		const option = screen.getByRole('radio');
+		fireEvent.click(option);
+		expect(onClickMock).not.toHaveBeenCalled();
+	});
+
+	it('allows to uncheck modality if checkboxStyle = true and onUncheck', () => {
+		const onClickMock = vi.fn();
+
+		render(
+			<RadioOption
+				id="radio-option"
+				label="Test Option"
+				onCheck={onClickMock}
+				onUncheck={onClickMock}
+				checkboxStyle={true}
+				checked
+			/>
+		);
+
+		const option = screen.getByRole('radio');
+		fireEvent.click(option);
+		expect(onClickMock).toHaveBeenCalled();
+	});
+
 	it('sets the tabIndex to 0 when unchecked', () => {
 		const { getByRole } = render(
 			<RadioOption id="radio-option" label="Test Option" checked={false} />

package/src/components/shared/Radio/RadioOption.tsx

@@ -40,6 +40,7 @@ function LunaticRadioOption({
 	detailLabel,
 	detailValue,
 	onCheck,
+	onUncheck,
 }: Props) {
 	const divEl = useRef<HTMLDivElement>(null);
 	const isEnabled = !disabled && !readOnly;
@@ -48,6 +49,10 @@ function LunaticRadioOption({
 
 	const onClickOption = () => {
 		if (!isEnabled || !onCheck || checked) {
+			// for checkboxStyle=true (only used by CheckboxOne) , we allow uncheck
+			if (checkboxStyle && onUncheck) {
+				onUncheck();
+			}
 			return;
 		}
 		onCheck();

package/src/use-lunatic/commons/compile-controls.ts

@@ -35,7 +35,8 @@ const isLoopComponent = (
 };
 
 /**
- * Check if components of the current page have errors, and return a map of error (indexed by component ID)
+ * Check if components of the current page have errors, and return a map of
+ * errors (indexed by component ID).
  */
 function checkComponents(
 	state: StateForControls,
@@ -93,7 +94,7 @@ function checkControls(
 }
 
 /**
- * Figure out the number of iterations of a component
+ * Figure out the number of iterations of a component.
  */
 function computeIterations(
 	component: InterpretedComponent | ComponentDefinition,
@@ -210,7 +211,7 @@ function hasCriticalError(errors?: Record<string, LunaticError[]>): boolean {
 }
 
 /**
- * Check controls for currently visible components and output errors
+ * Check controls for currently visible components and output errors.
  */
 export function compileControls(state: StateForControls) {
 	const components = replaceComponentSequence(getComponentsFromState(state));

package/src/use-lunatic/commons/variables/lunatic-variables-store.ts

@@ -19,23 +19,23 @@ import {
 	VTLMissingDependency,
 } from './errors';
 
-// Interpret counter, used for testing purpose
+/** Interpret counter. Used for testing purpose. */
 let interpretCount = 0;
-// Special variable that will take the current iteration value
+/** Special variable that will take the current iteration value. */
 const iterationVariableName = 'GLOBAL_ITERATION_INDEX';
 
 type IterationLevel = number[];
 export type EventArgs = {
 	change: {
-		// Name of the changed variable
+		/** Name of the changed variable. */
 		name: string;
-		// New value for the variable
+		/** New value for the variable. */
 		value: unknown;
-		// Iteration changed (for array)
+		/** Iteration changed (for array). */
 		iteration?: IterationLevel | undefined;
-		// What triggered this change
+		/** What triggered this change. */
 		cause?: 'resizing' | 'cleaning';
-		// Extra sent when setting the variable
+		/** Extra sent when setting the variable. */
 		[extra: string]: unknown;
 	};
 };
@@ -220,7 +220,7 @@ export class LunaticVariablesStore {
 		this.eventTarget.removeEventListener(eventName, cb as EventListener);
 	}
 
-	// Retrieve the number of interpret() run (used in testing only)
+	/** Retrieve the number of interpret() run (used in testing only). */
 	get interpretCount() {
 		return interpretCount;
 	}
@@ -249,25 +249,25 @@ export class LunaticVariablesStore {
 }
 
 class LunaticVariable {
-	// Last time the value was updated (changed)
+	/** Last time the value was updated (changed). */
 	public updatedAt = new Map<undefined | string, number>();
-	// Last time "calculation" was run (for calculated variable)
+	/** Last time "calculation" was run (for calculated variable). */
 	private calculatedAt = new Map<undefined | string, number>();
-	// Internal value for the variable
+	/** Internal value for the variable. */
 	private value: unknown;
-	// List of dependencies, ex: ['FIRSTNAME', 'LASTNAME']
+	/** List of dependencies, ex: ['FIRSTNAME', 'LASTNAME']. */
 	private dependencies?: string[];
-	// Expression for calculated variable
+	/** Expression for calculated variable. */
 	public readonly expression?: string;
-	// Dictionary holding all the available variables
+	/** Dictionary holding all the available variables. */
 	private readonly dictionary?: Map<string, LunaticVariable>;
-	// Specific iteration depth to get value from dependencies (used for yAxis for instance)
+	/** Specific iteration depth to get value from dependencies (used for yAxis for instance). */
 	private readonly iterationDepth?: number;
-	// For calculated variable, shape is copied from another variable
+	/** For calculated variable, shape is copied from another variable. */
 	private readonly shapeFrom?: string[];
-	// Keep a record of variable name (optional, used for debug)
+	/** Keep a record of variable name (optional, used for debug). */
 	public readonly name?: string;
-	// Count the number of calculation
+	/** Count the number of calculation. */
 	public calculatedCount = 0;
 
 	constructor(

package/src/use-lunatic/hooks/use-loop-variables.ts

@@ -2,7 +2,7 @@ import type { LunaticComponentDefinition, LunaticReducerState } from '../type';
 import { useMemo } from 'react';
 
 /**
- * Extract the list of variables used for the current loop
+ * Extract the list of variables used for the current loop.
  */
 export function useLoopVariables(
 	pager: LunaticReducerState['pager'],

package/src/use-lunatic/hooks/use-page-has-response.ts

@@ -4,7 +4,7 @@ import type { LunaticComponentDefinition, LunaticReducerState } from '../type';
 import type { LunaticComponentProps } from '../../components/type';
 
 /**
- * Check if a page has one response (value is filled for at least one field)
+ * Check if a page has one response (value is filled for at least one field).
  */
 export function usePageHasResponse(
 	components: LunaticComponentProps[],
@@ -67,10 +67,10 @@ export function usePageHasResponse(
 }
 
 /**
- * Check if a value is empty
- * - null ou undefined ou ''
- * - for arrays, every item must be empty
- * - for objects, every value must be empty
+ * Check if a value is empty.
+ * - `null`, `undefined` or `''`.
+ * - for arrays, every item must be empty.
+ * - for objects, every value must be empty.
  */
 function isEmpty(value: unknown): boolean {
 	// Array is empty if all items are empty
@@ -86,7 +86,7 @@ function isEmpty(value: unknown): boolean {
 }
 
 /**
- * For complex component we need to inspect child components, interpret the response value
+ * For complex component we need to inspect child components, interpret the response value.
  */
 function isSubComponentsEmpty(
 	components: (LunaticComponentProps | LunaticComponentDefinition)[],

package/src/use-lunatic/hooks/useOverview.ts

@@ -18,7 +18,7 @@ export type InterpretedLunaticOverviewItem = {
 };
 
 /**
- * Hook to build a filled overview everytime the deps change
+ * Build a filled overview everytime the deps change.
  */
 export const useOverview = (
 	{
@@ -36,7 +36,7 @@ export const useOverview = (
 };
 
 /**
- * Use lunatic data to interpret the static overview (calculated on init) with the real data
+ * Use Lunatic data to interpret the static overview (calculated on init) with the real data.
  */
 const interpretOverview = (
 	overviewItems: LunaticOverviewItem[],
@@ -71,7 +71,7 @@ const interpretOverview = (
 };
 
 /**
- * Interpret expression inside an item (label & condition)
+ * Interpret expression inside an item (label & condition).
  */
 const interpretOverviewItem = (
 	items: InterpretedLunaticOverviewItem[],
@@ -127,7 +127,7 @@ const interpretOverviewItem = (
 };
 
 /**
- * Set the current property in the correct overview item
+ * Set the current property in the correct overview item.
  */
 const applyCurrentPage = (
 	items: InterpretedLunaticOverviewItem[],

package/src/use-lunatic/hooks/useWarnDepChange.ts

@@ -3,8 +3,9 @@ import type { LunaticLogger } from '../logger/type';
 import { useRefSync } from '../../hooks/useRefSync';
 
 /**
- * Log a warning when the variable change
- * ensure that we received a memoized value and help debug
+ * Log a warning when the variable change.
+ *
+ * Ensure that we received a memoized value and help debug.
  */
 export function useWarnDepChange(
 	variable: unknown,

package/src/use-lunatic/lunatic-context.tsx

@@ -17,8 +17,11 @@ const LunaticContext = createContext({
 	refusedButton: D.RF,
 	componentsOptions: { detailAlwaysDisplayed: false },
 });
-/** Provide `missing` `missingStrategy`, `shortcut` and `missingShortcut`, `dontKnowButton`, `refusedButton` to Missing component
- *  to manage non-response buttons and shortcut */
+/**
+ * Provide `missing`, `missingStrategy`, `shortcut` and `missingShortcut`,
+ * `dontKnowButton`, `refusedButton` to `Missing` component to manage
+ * non-response buttons and shortcut.
+ */
 export const useLunaticMissing = () => {
 	const {
 		missing,

package/src/use-lunatic/props/propOptions.ts

@@ -18,6 +18,7 @@ export type InterpretedOption = {
 	detailValue?: string | null;
 	onDetailChange?: (value: string) => void;
 	onCheck?: () => void;
+	onUncheck?: () => void;
 };
 
 /**
@@ -86,6 +87,10 @@ export function getOptionsProp(
 					{ name: definition.response.name, value: option.value },
 				]);
 			},
+			// for CheckboxOne, we allow uncheck
+			onUncheck: () => {
+				handleChanges([{ name: definition.response.name, value: null }]);
+			},
 			detailValue:
 				'detail' in option && option.detail
 					? variables.get(option.detail.response.name, iteration)

package/src/use-lunatic/type.ts

@@ -35,6 +35,7 @@ export type LunaticOverviewItem = {
 
 export type LunaticSuggester = SuggesterDefinition;
 
+/** Survey data. */
 export type LunaticData = Partial<
 	Record<Exclude<VariableType, 'COLLECTED'>, Record<string, unknown>> & {
 		COLLECTED: Record<string, LunaticCollectedValue>;
@@ -45,6 +46,10 @@ export type LunaticValues = {
 	[variableName: string]: unknown;
 };
 
+/**
+ * Errors returned by `useLunatic` hook when an input check is made with their
+ * id, criticity, type and the message to display to the user.
+ */
 export type LunaticError = Pick<
 	ControlDefinition,
 	'id' | 'criticality' | 'typeOfControl'
@@ -55,8 +60,17 @@ export type LunaticError = Pick<
 export type VariableType = 'COLLECTED' | 'EXTERNAL' | 'CALCULATED';
 export type LunaticExpression = VTLExpression | VTLScalarExpression;
 
+/**
+ * Page numerotation.
+ *
+ * String representing a location in the survey. It has one of the following
+ * format:
+ * - [page].[sous-page]#[iteration], when we are in a loop or a roundabount
+ * - [page]
+ */
 export type PageTag = `${number}.${number}#${number}` | `${number}`;
 
+/** Variables provided to Lunatic through the source and used internally in a store. */
 export type LunaticVariable = Variable;
 export type LunaticCollectedValue = Partial<{
 	COLLECTED: unknown;
@@ -76,16 +90,52 @@ export type LunaticStateVariable = {
 	};
 }[LunaticVariable['variableType']];
 
+/**
+ * Contains informations about navigation (last page reached, number of pages, subpages, etc.).
+ *
+ * This is the object used internally to determine where we are in the navigation.
+ *
+ * When we are in a loop, the pager will have additional properties.
+ */
 export type LunaticPager = {
+	/** Last page reached. */
 	lastReachedPage?: PageTag;
+	/** Last page of the survey. */
 	maxPage: number;
-	nbSubPages?: number;
+	/** Current page. */
 	page: number;
+
+	/**
+	 * Current subpage.
+	 *
+	 * Only in a loop.
+	 */
 	subPage?: number;
-	// Iteration index (starting at 0)
+	/**
+	 * Number of pages in a loop.
+	 *
+	 * Only in a loop.
+	 */
+	nbSubPages?: number;
+	/**
+	 * Iteration index (starts at 0).
+	 *
+	 * Only in a loop.
+	 */
 	iteration?: number;
+	/**
+	 * Number of iterations (i.e. number of people).
+	 *
+	 * Only in a loop.
+	 */
 	nbIterations?: number;
+	/**
+	 * Only in a loop.
+	 */
 	shallowIteration?: number;
+	/**
+	 * Only in a loop.
+	 */
 	linksIterations?: number[];
 };
 
@@ -107,25 +157,25 @@ export type LunaticReducerState = {
 					components: LunaticSource['components'];
 					isLoop: true;
 					iterations: VTLScalarExpression;
-					// Variables affecting this loop
+					/** Variables affecting this loop. */
 					loopDependencies: string[];
-					// List of child pages (ex: ['20.1', '20.2']
+					/** List of child pages (ex: ['20.1', '20.2'] */
 					subPages: string[];
 			  };
 	};
-	// Run and expression using the value from the state
+	/** Run an expression using the value from the state. */
 	executeExpression: <T = unknown>(
 		expression: VTLExpression,
 		args?: {
 			iteration?: number | number[];
-			// @deprecated
+			/** @deprecated  */
 			bindingDependencies?: string[];
 			deps?: string[];
 		}
 	) => T;
 	isInLoop: boolean;
 	updatedAt: number;
-	// Update the value collected for the variable
+	/** Update the value collected for the variable. */
 	updateBindings: (
 		variableName: string,
 		value: unknown,
@@ -136,78 +186,164 @@ export type LunaticReducerState = {
 	};
 };
 
+/** Specific behaviour options defined in the {@link useLunatic} hook. */
 export type LunaticOptions = {
+	/** Ignore filters. (default: `false`) */
 	disableFilters?: boolean;
+	/** Enable VTL and Markdown support. */
 	features?: ('MD' | 'VTL')[];
 	preferences?: ['COLLECTED'];
+	/** Key in which the data is saved. (default: `"COLLECTED"`) */
 	savingType?: 'COLLECTED';
+	/** Function called when a variable is changed by a user input (must be memoized as it is used in dependency of a `useCallback` by the library). */
 	onChange?: LunaticChangesHandler;
 	onVariableChange?: (event: LunaticVariablesStoreEvents['change']) => void;
+	/**
+	 * Not yet implemented.
+	 *
+	 * Enable management mode which allow to handle multiple states of the same variable (used by recovery positions).
+	 *
+	 * The administrator can switch between `COLLECTED`, `EDITED`, `INPUTTED` modes. (default: `false`)
+	 */
 	management?: boolean;
-	// enable shortcut on radio/checkbox/missing buttons
+	/** Enable keyboard shortcuts for checkboxes, radio buttons and missing buttons (default: `false`). */
 	shortcut?: boolean;
+	/** Starting page at launch. (default: `"1"`) */
 	initialPage?: PageTag;
+	/** Furthest page the user ever reached. */
 	lastReachedPage?: PageTag;
+	/** Enable the preemptive loading of suggester data on Lunatic initialization. (default: `false`) */
 	autoSuggesterLoading?: boolean;
+	/** Function called to fetch nomenclatures used by the suggesters. */
 	getReferentiel?: (name: string) => Promise<Array<IndexEntry>>;
-	// Enable controls for data (form validation)
+	/** Enable data controls (form validation). (default: `false`) */
 	activeControls?: boolean;
+	/** Enable overview system. (default: `false`) */
 	withOverview?: boolean;
+	/** Enable missing system. (default: `false`) */
 	missing?: boolean;
+	/** Function triggered when a missing button is clicked. */
 	missingStrategy?: () => void;
+	/** Keyboard shortcut that triggers missing buttons. */
 	missingShortcut?: { dontKnow: string; refused: string };
+	/** "Don't know" button label. */
 	dontKnowButton?: string;
+	/** "Refused" button label. */
 	refusedButton?: string;
-	// Enable change tracking to keep a track of what variable changed (allow using getChangedData())
+	/** Enable change tracking to keep a track of what variable changed (allow using getChangedData()). (default: `false`) */
 	trackChanges?: boolean;
 	logger?: LunaticLogger;
 	componentsOptions?: { detailAlwaysDisplayed?: boolean };
 };
 
-// Type representing the return type of "useLunatic()"
+/**
+ * Return type of {@link useLunatic}.
+ *
+ * Allow to operate the survey.
+ */
 export type LunaticState = {
+	/** Current pager. */
 	pager: LunaticPager;
 	overview: InterpretedLunaticOverviewItem[];
+	/** Current page numerotation. */
 	pageTag: PageTag;
+	/** Date of the last `handleChange` function call. */
 	updatedAt: number;
+	/** Necessary component that must wraps `LunaticComponents` to make the library works. */
 	Provider: FunctionComponent<PropsWithChildren>;
+	/** Whether or not we're in a loop. */
 	isInLoop: boolean;
+	/** Current loop's variables. */
 	loopVariables: string[];
+	/** Whether or not we're on the survey first page. */
 	isFirstPage: boolean;
+	/** Whether or not we're on the survey last page (we reached `maxPage`). */
 	isLastPage: boolean;
-	// Errors for the form
+	/** Errors in the survey. */
 	errors?: { [page: string]: { [id: string]: LunaticError[] } };
-	// Contains the errors for the current page / iteration
+	/** Errors in the current page / iteration. */
 	currentErrors?: { [id: string]: LunaticError[] };
-	// Errors
+	/** Errors in modal. */
 	modalErrors?: Record<string, LunaticError[]>;
+	/** Navigate to a specific page. */
 	goToPage: (page: {
 		page: PageTag | number;
 		iteration?: number;
 		nbIterations?: number;
 		subPage?: number;
 	}) => void;
-	// Enable components to independently navigate next/previous
+	/** Navigate to the next page. */
 	goNextPage: () => void;
+	/** Navigate to the previous page. */
 	goPreviousPage: () => void;
+	/** Allow to fetch controls. */
 	compileControls: () => {
 		currentErrors: Record<string, LunaticError[]> | undefined;
 		isCritical: boolean;
 	};
+	/**
+	 * Components to display in the current page.
+	 *
+	 * Return an array with the various components' properties. The orchestrator
+	 * has to handle how they are displayed, using the `componentType` property to
+	 * select the appropriate component.
+	 *
+	 * @example
+	 * // using `LunaticComponents`
+	 * import { useLunatic, LunaticComponents } from '@inseefr/lunatic';
+	 *
+	 * function App({ source, data }) {
+	 *   const { getComponents, Provider } = useLunatic(source, data, {});
+	 *   const components = getComponents();
+	 *
+	 *   return (
+	 *     <Provider>
+	 *       <LunaticComponents components={components} />
+	 *     </Provider>
+	 *   );
+	 * }
+	 *
+	 * @example
+	 * // using custom components
+	 * import { useLunatic, LunaticComponents } from '@inseefr/lunatic';
+	 *
+	 * const customCompoonents = {
+	 *   Input: MyCustomInput,
+	 *   InputNumber: MyCustomInputNumber,
+	 * };
+	 *
+	 * function App({ source, data }) {
+	 *   const { getComponents, Provider } = useLunatic(source, data, {});
+	 *   const components = getComponents();
+	 *
+	 *   return (
+	 *     <Provider>
+	 *       <LunaticComponents components={components} slots={customComponents} />
+	 *     </Provider>
+	 *   );
+	 * }
+	 *
+	 * @see {@link LunaticComponents}
+	 */
 	getComponents: () => LunaticComponentProps[];
+	/** Get data collected by the survey. */
 	getData: (
 		withRefreshedCalculated: boolean,
 		variableNames?: string[]
 	) => LunaticData;
-	getChangedData: (reset: boolean) => LunaticData;
+	/** Get data that have changed since last reset. Returns the same thing as `getData()`. */
+	getChangedData: (reset?: boolean) => LunaticData;
+	/** Empty the store of changed variables. */
 	resetChangedData: () => void;
+	/** Return `true` as soon as the current page has at least one answer. */
 	hasPageResponse: () => boolean;
-	// This is used for testing purpose only
+	/** Used for testing purpose only. */
 	testing: {
 		handleChanges: LunaticChangesHandler;
 	};
 };
 
+/** Function taking as arguments the various changes the user has made. */
 export type LunaticChangesHandler = (
 	args: {
 		name: string;

package/src/use-lunatic/use-lunatic.ts

@@ -66,11 +66,19 @@ const defaultOptions = {
 	componentsOptions: { detailAlwaysDisplayed: false },
 } satisfies LunaticOptions;
 
+/** The first library entrypoint is the `useLunatic` hook. */
 export function useLunatic(
+	/**
+	 * JSON representation of our survey unit in the Lunatic Model.
+	 *
+	 * {@link https://github.com/InseeFr/Lunatic-Model}
+	 */
 	source: LunaticSource,
+	/** Initial survey data (i.e. if it has been partially filled). */
 	data: LunaticData = DEFAULT_DATA,
+	/** Specific behaviour options. */
 	argOptions: LunaticOptions = empty
-) {
+): LunaticState {
 	const options = mergeDefault(argOptions, defaultOptions);
 	const {
 		disableFilters,
@@ -106,7 +114,7 @@ export function useLunatic(
 		reducerInitializer
 	);
 
-	// Required context provider: cleaner than prop drilling through every component
+	/** Required context provider: cleaner than prop drilling through every component */
 	const Provider = useMemo(
 		() =>
 			createLunaticProvider({
@@ -157,6 +165,7 @@ export function useLunatic(
 		},
 		[dispatch]
 	);
+
 	const handleChanges = useCallback<LunaticChangesHandler>(
 		(responses) => {
 			dispatch(handleChangesAction(responses));