@evenicanpm/admin-integrate 1.8.1 → 2.0.1

package/src/components/templatesV2/inputs/field-names.ts

@@ -0,0 +1,8 @@
+/**
+ * Reserved form/config field names used by the template wizard.
+ * Use this enum instead of string literals to avoid typos and keep a single source of truth.
+ */
+export enum ReservedFieldName {
+	ProcessTemplateId = "processTemplateId",
+	IsUnique = "isUnique",
+}

package/src/components/templatesV2/inputs/form-type.ts

@@ -0,0 +1,54 @@
+import type { TemplateInputSearchQueryKey } from "@evenicanpm/admin-integrate/api/templates/queries/types";
+import type { FieldValue, ProcessTemplateInputSchema } from "../types";
+import type { InputType } from "./input-type";
+export type TableRow = Record<string, string | number | boolean | null>;
+
+export type SetRowsFn = (rows: TableRow[]) => void;
+
+/** Used for TEXT_UNIQUE_IDENTIFIER when updating a sibling field (e.g. `isUnique`). */
+export type SearchInputExtendedSetValue = (
+	v: FieldValue,
+	fieldName?: string,
+) => void;
+
+export interface InputTableProps {
+	rows: TableRow[];
+	setRows: SetRowsFn;
+	schemas: ProcessTemplateInputSchema[];
+	tableError: string | null;
+	readOnly?: boolean;
+}
+
+export type SearchInputWrapperProps = {
+	fieldName?: string;
+	inputType:
+		| InputType.MULTI_TEXT_SEARCH
+		| InputType.TEXT_SEARCH
+		| InputType.TEXT_UNIQUE_IDENTIFIER;
+
+	label: string;
+	value: string | string[];
+	setValue:
+		| ((v: string) => void)
+		| ((v: string[]) => void)
+		| SearchInputExtendedSetValue;
+
+	placeholder?: string | null;
+	helpText?: string | null;
+	error?: string | null;
+
+	queryName: TemplateInputSearchQueryKey;
+
+	/** Raw query name (e.g. Templates_GetSourceEndpoints) for getFieldValues API when inputType is TEXT_SEARCH */
+	validationQuery?: string;
+
+	/** Used by TextSearchInput to apply selected template config into the form */
+	handleFieldChange?: (
+		templateId: string,
+		fieldName: string,
+		value: FieldValue,
+	) => void;
+
+	/** Call when the search input blurs so errors show on focus out */
+	onBlur?: () => void;
+};

package/src/components/templatesV2/inputs/index.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+export { FormikPageBody } from "./FormikPageBody";
+export { ReservedFieldName } from "./field-names";
+export type { SearchInputWrapperProps } from "./form-type";
+export { InputType, isHiddenInputType } from "./input-type";
+export {
+	CheckboxInput,
+	NumberInput,
+	SelectorInput,
+	TextInput,
+} from "./primitives";
+export { renderFormControl, renderSearchInput } from "./renderers";
+
+export {
+	MultiTextSearchInput,
+	SearchInputWrapper,
+	TextSearchInput,
+	useSearchInput,
+} from "./search";
+export { TemplateSearchQueryKey } from "./search/search-query-key";
+
+export { InputTable } from "./table";
+export {
+	applyTemplateConfig,
+	arrangeInputs,
+	getSelectorOptionsFromInput,
+	getTableRowErrors,
+	parseQueryName,
+	renderReadOnlyText,
+	toStringArray,
+} from "./utils";
+export type { InputRow } from "./utils/arrangeInputs";

package/src/components/templatesV2/inputs/input-type.ts

@@ -0,0 +1,23 @@
+export enum InputType {
+	TEXT = "text",
+	NUMBER = "number",
+	CHECKBOX = "checkbox",
+	SELECTOR = "selector",
+	INPUT_TABLE = "input-table",
+	TEXT_SEARCH = "text-search",
+	MULTI_TEXT_SEARCH = "multi-text-search",
+	TEXT_UNIQUE_IDENTIFIER = "text-unique-identifier",
+	HIDDEN = "hidden",
+	HIDDEN_NUMBER = "hidden-number",
+	HIDDEN_NUMBER_OR_NULL = "hidden-number-or-null",
+}
+
+export function isHiddenInputType(
+	inputType: string | null | undefined,
+): boolean {
+	return (
+		inputType === InputType.HIDDEN ||
+		inputType === InputType.HIDDEN_NUMBER ||
+		inputType === InputType.HIDDEN_NUMBER_OR_NULL
+	);
+}

package/src/components/templatesV2/inputs/primitives/CheckboxInput.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import type { SxProps, Theme } from "@mui/material";
+import { Box, Checkbox, FormControlLabel, FormHelperText } from "@mui/material";
+
+export function CheckboxInput({
+	label,
+	checked,
+	setChecked,
+	helpText,
+	readOnly,
+	disabled,
+	formHelperTextSx,
+}: Readonly<{
+	label: string;
+	checked: boolean;
+	setChecked: (v: boolean) => void;
+	helpText?: string | null;
+	readOnly?: boolean;
+	/** Disable without read-only (e.g. while validating). */
+	disabled?: boolean;
+	/** Optional sx for the helper text (e.g. color: 'success.main' or 'error.main'). */
+	formHelperTextSx?: SxProps<Theme>;
+}>) {
+	return (
+		<Box>
+			<FormControlLabel
+				control={
+					<Checkbox
+						checked={checked}
+						onChange={(e) => setChecked(e.target.checked)}
+					/>
+				}
+				label={label}
+				disabled={disabled ?? readOnly}
+			/>
+
+			<FormHelperText
+				sx={{ mt: -1.5, mb: 1, marginLeft: 0, ...formHelperTextSx }}
+			>
+				{helpText || "  "}
+			</FormHelperText>
+		</Box>
+	);
+}

package/src/components/templatesV2/inputs/primitives/NumberInput.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import type { SxProps, Theme } from "@mui/material";
+import { TextField } from "@mui/material";
+import { renderReadOnlyText } from "../utils/renderReadOnlyText";
+
+export function NumberInput({
+	label,
+	placeholder,
+	value,
+	setValue,
+	error,
+	helpText,
+	readOnly,
+	disabled,
+	onBlur,
+	onFocus,
+	formHelperTextSx,
+}: Readonly<{
+	label: string;
+	placeholder?: string | null;
+	value: number | "" | null;
+	setValue: (v: number | "") => void;
+	error?: string | null;
+	helpText?: string | null;
+	readOnly?: boolean;
+	/** Disable input without switching to read-only text (e.g. while validating). */
+	disabled?: boolean;
+	onBlur?: () => void;
+	onFocus?: () => void;
+	/** Optional sx for the helper text (e.g. color: 'success.main' for validation success). */
+	formHelperTextSx?: SxProps<Theme>;
+}>) {
+	if (readOnly) return renderReadOnlyText(label, value);
+
+	return (
+		<TextField
+			type="number"
+			label={label}
+			value={value ?? ""}
+			onChange={(e) =>
+				setValue(e.target.value === "" ? "" : Number(e.target.value))
+			}
+			onBlur={onBlur}
+			onFocus={onFocus}
+			placeholder={placeholder ?? undefined}
+			fullWidth
+			error={Boolean(error)}
+			helperText={error ?? helpText ?? " "}
+			disabled={disabled}
+			slotProps={{
+				formHelperText: {
+					sx: { marginLeft: 0, ...formHelperTextSx },
+				},
+			}}
+		/>
+	);
+}

package/src/components/templatesV2/inputs/primitives/SelectorInput.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import type { SxProps, Theme } from "@mui/material";
+import { Autocomplete, Box, TextField } from "@mui/material";
+import { renderReadOnlyText } from "../utils/renderReadOnlyText";
+
+/** Option can be a plain string (label = value) or { label, value } for API-backed options. */
+export type SelectorOption = string | { label: string; value: string };
+
+function getOptionLabel(opt: SelectorOption): string {
+	return typeof opt === "string" ? opt : opt.label;
+}
+
+function getOptionValue(opt: SelectorOption): string {
+	return typeof opt === "string" ? opt : opt.value;
+}
+
+function optionEquals(opt: SelectorOption, value: string): boolean {
+	return getOptionValue(opt) === value;
+}
+
+export function SelectorInput({
+	fieldName,
+	label,
+	value,
+	setValue,
+	helpText,
+	error,
+	options,
+	insideTable = false,
+	minWidth,
+	readOnly,
+	disabled,
+	onBlur,
+	onFocus,
+	formHelperTextSx,
+}: Readonly<{
+	fieldName: string;
+	label: string;
+	value: string;
+	setValue: (v: string) => void;
+	helpText?: string | null;
+	error?: string | null;
+	/** String options (label = value) or { label, value } for API-backed options. */
+	options?: SelectorOption[];
+	insideTable?: boolean;
+	minWidth?: number;
+	readOnly?: boolean;
+	/** Disable input without switching to read-only text (e.g. while validating). */
+	disabled?: boolean;
+	onBlur?: () => void;
+	onFocus?: () => void;
+	/** Optional sx for the helper text (e.g. color: 'success.main' for validation success). */
+	formHelperTextSx?: SxProps<Theme>;
+}>) {
+	const opts = options ?? [];
+	const allowFreeText = opts.length === 0;
+	const id = `selector-${fieldName}`;
+	const currentValue = value ?? "";
+	const selectedOption =
+		opts.find((o) => optionEquals(o, currentValue)) ?? (currentValue || null);
+
+	if (readOnly)
+		return renderReadOnlyText(insideTable ? undefined : label, value);
+
+	return (
+		<Box
+			sx={{
+				minWidth: minWidth ?? (insideTable ? 220 : undefined),
+				width: "100%",
+			}}
+		>
+			<Autocomplete<SelectorOption, false, false, boolean>
+				id={id}
+				disablePortal={insideTable}
+				options={opts}
+				getOptionLabel={getOptionLabel}
+				isOptionEqualToValue={(opt, v) =>
+					v == null
+						? false
+						: opt === v ||
+							optionEquals(opt, typeof v === "string" ? v : getOptionValue(v))
+				}
+				freeSolo={allowFreeText}
+				value={selectedOption ?? null}
+				onChange={(_e, val) => setValue(val != null ? getOptionValue(val) : "")}
+				onInputChange={(_e, val) => setValue(val)}
+				disabled={disabled ?? readOnly}
+				renderInput={(params) => (
+					<TextField
+						{...params}
+						size={insideTable ? "small" : "medium"}
+						label={label}
+						name={fieldName}
+						error={Boolean(error)}
+						helperText={error ?? helpText ?? " "}
+						fullWidth
+						disabled={disabled ?? readOnly}
+						onBlur={onBlur}
+						onFocus={onFocus}
+						slotProps={{
+							formHelperText: {
+								sx: { marginLeft: 0, ...formHelperTextSx },
+							},
+						}}
+					/>
+				)}
+			/>
+		</Box>
+	);
+}

package/src/components/templatesV2/inputs/primitives/TextInput.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import type { SxProps, Theme } from "@mui/material";
+import { TextField } from "@mui/material";
+import { renderReadOnlyText } from "../utils/renderReadOnlyText";
+
+export function TextInput({
+	label,
+	placeholder,
+	value,
+	setValue,
+	error,
+	helpText,
+	readOnly,
+	disabled,
+	onBlur,
+	onFocus,
+	formHelperTextSx,
+}: Readonly<{
+	label: string;
+	placeholder?: string | null;
+	value: string;
+	setValue: (v: string) => void;
+	error?: string | null;
+	helpText?: string | null;
+	readOnly?: boolean;
+	/** Disable input without switching to read-only text (e.g. while validating). */
+	disabled?: boolean;
+	onBlur?: () => void;
+	onFocus?: () => void;
+	/** Optional sx for the helper text (e.g. color: 'success.main' for validation success). */
+	formHelperTextSx?: SxProps<Theme>;
+}>) {
+	if (readOnly) return renderReadOnlyText(label, value);
+
+	return (
+		<TextField
+			label={label}
+			value={value ?? ""}
+			onChange={(e) => setValue(e.target.value)}
+			onBlur={onBlur}
+			onFocus={onFocus}
+			placeholder={placeholder ?? undefined}
+			fullWidth
+			error={Boolean(error)}
+			helperText={error ?? helpText ?? "  "}
+			disabled={disabled}
+			slotProps={{
+				formHelperText: {
+					sx: { minHeight: 16, marginLeft: 0, ...formHelperTextSx },
+				},
+			}}
+		/>
+	);
+}

package/src/components/templatesV2/inputs/primitives/TextWithQueryInput.tsx

@@ -0,0 +1,292 @@
+"use client";
+
+import type { SxProps, Theme } from "@mui/material";
+import { Box } from "@mui/material";
+import * as React from "react";
+import { validateFieldOnCheck } from "../../../../api/templates/queries/validate-field-on-check.server";
+import { InputType } from "../input-type";
+import { renderReadOnlyText } from "../utils/renderReadOnlyText";
+import { CheckboxInput } from "./CheckboxInput";
+import { NumberInput } from "./NumberInput";
+import type { SelectorOption } from "./SelectorInput";
+import { SelectorInput } from "./SelectorInput";
+import { TextInput } from "./TextInput";
+
+export type TextWithQueryInputType =
+	| InputType.TEXT
+	| InputType.NUMBER
+	| InputType.SELECTOR
+	| InputType.CHECKBOX;
+
+export type TextWithQueryValue = string | number | boolean;
+
+function valueToString(value: TextWithQueryValue): string {
+	if (value === "" || value == null) return "";
+	if (typeof value === "boolean") return value ? "true" : "false";
+	return String(value).trim();
+}
+
+function getEffectiveValidation(
+	submitValidationResult:
+		| { isValid: boolean; message: string }
+		| null
+		| undefined,
+	validation: { isValid: boolean; message: string } | null,
+): { isValid: boolean; message: string } | null {
+	if (submitValidationResult != null) {
+		return {
+			isValid: submitValidationResult.isValid,
+			message: submitValidationResult.message,
+		};
+	}
+	return validation;
+}
+
+function getDisplayError(
+	validating: boolean,
+	isError: boolean,
+	helperMessage: string,
+): string | undefined {
+	if (validating) return undefined;
+	if (isError) return helperMessage;
+	return undefined;
+}
+
+function formatReadOnlyValue(
+	value: TextWithQueryValue,
+): string | number | boolean {
+	if (typeof value === "boolean") return value ? "Yes" : "No";
+	return value;
+}
+
+interface DisplayStateInput {
+	error?: string | null;
+	validation: { isValid: boolean; message: string } | null;
+	submitValidationResult?: { isValid: boolean; message: string } | null;
+	helpText?: string | null;
+	validating: boolean;
+	readOnly?: boolean;
+}
+
+function getInputDisplayState({
+	error,
+	validation,
+	submitValidationResult,
+	helpText,
+	validating,
+	readOnly,
+}: DisplayStateInput): {
+	displayError: string | undefined;
+	displayHelpText: string;
+	formHelperTextSx: SxProps<Theme>;
+	isDisabled: boolean;
+} {
+	const showError = Boolean(error);
+	const effectiveValidation = getEffectiveValidation(
+		submitValidationResult,
+		validation,
+	);
+	const helperMessage =
+		showError && error
+			? error
+			: (effectiveValidation?.message ?? helpText ?? "");
+	const isSuccess = effectiveValidation?.isValid === true && !showError;
+	const isError = showError || effectiveValidation?.isValid === false;
+	const displayError = getDisplayError(validating, isError, helperMessage);
+	const displayHelpText = validating ? "Checking…" : helperMessage;
+	const isDisabled = Boolean(readOnly || validating);
+	const formHelperTextSx: SxProps<Theme> = {
+		...(validating && { color: "text.secondary" }),
+		...(isSuccess && !validating && { color: "success.main" }),
+		...(isError && !validating && { color: "error.main" }),
+	};
+	return {
+		displayError,
+		displayHelpText,
+		formHelperTextSx,
+		isDisabled,
+	};
+}
+
+export type SubmitValidationResult = { isValid: boolean; message: string };
+
+export interface TextWithQueryInputProps {
+	inputType: TextWithQueryInputType;
+	label: string;
+	value: TextWithQueryValue;
+	setValue: (v: TextWithQueryValue) => void;
+	error?: string | null;
+	helpText?: string | null;
+	readOnly?: boolean;
+	onBlur?: () => void;
+	fieldName: string;
+	validationQuery: string;
+	fieldId: string;
+	validateFormikBeforeApi?: () => Promise<boolean>;
+	setFieldValidationInProgress?: (inProgress: boolean) => void;
+	placeholder?: string | null;
+	options?: SelectorOption[];
+	/** Result from validateFieldOnSubmit (on Next click); shown below field. */
+	submitValidationResult?: SubmitValidationResult | null;
+}
+
+export function TextWithQueryInput({
+	inputType,
+	label,
+	value,
+	setValue,
+	error,
+	helpText,
+	readOnly,
+	onBlur,
+	fieldName,
+	validationQuery,
+	fieldId,
+	validateFormikBeforeApi,
+	setFieldValidationInProgress,
+	placeholder,
+	options = [],
+	submitValidationResult,
+}: Readonly<TextWithQueryInputProps>) {
+	const [validation, setValidation] = React.useState<{
+		isValid: boolean;
+		message: string;
+	} | null>(null);
+	const [validating, setValidating] = React.useState(false);
+
+	const handleBlur = React.useCallback(async () => {
+		onBlur?.();
+		const strValue = valueToString(value);
+		if (!strValue && inputType !== InputType.CHECKBOX) {
+			setValidation(null);
+			return;
+		}
+		const formikValid = await (validateFormikBeforeApi?.() ??
+			Promise.resolve(true));
+		if (!formikValid) return;
+		setValidating(true);
+		setValidation(null);
+		setFieldValidationInProgress?.(true);
+		try {
+			const result = await validateFieldOnCheck({
+				input: {
+					fieldName,
+					fieldId,
+					value: strValue,
+				},
+			});
+			if (result) {
+				setValidation({
+					isValid: result.isValid ?? false,
+					message: result.message ?? "",
+				});
+			}
+		} catch {
+			setValidation({ isValid: false, message: "Validation failed" });
+		} finally {
+			setValidating(false);
+			setFieldValidationInProgress?.(false);
+		}
+	}, [
+		value,
+		inputType,
+		fieldName,
+		validationQuery,
+		onBlur,
+		validateFormikBeforeApi,
+		setFieldValidationInProgress,
+	]);
+
+	if (readOnly) {
+		const formattedValue = formatReadOnlyValue(value);
+		const readOnlyValue =
+			typeof formattedValue === "string" ||
+			typeof formattedValue === "number" ||
+			(Array.isArray(formattedValue) &&
+				formattedValue.every((v) => typeof v === "string"))
+				? formattedValue
+				: "";
+		return renderReadOnlyText(label, readOnlyValue);
+	}
+
+	const display = getInputDisplayState({
+		error,
+		validation,
+		submitValidationResult,
+		helpText,
+		validating,
+		readOnly,
+	});
+
+	const clearValidationAndSet = (v: TextWithQueryValue) => {
+		setValidation(null);
+		setValue(v);
+	};
+
+	if (inputType === InputType.TEXT) {
+		return (
+			<TextInput
+				label={label}
+				placeholder={placeholder}
+				value={(value as string) ?? ""}
+				setValue={clearValidationAndSet}
+				error={display.displayError}
+				helpText={display.displayHelpText}
+				readOnly={readOnly}
+				disabled={display.isDisabled}
+				onBlur={handleBlur}
+				formHelperTextSx={display.formHelperTextSx}
+			/>
+		);
+	}
+	if (inputType === InputType.NUMBER) {
+		return (
+			<NumberInput
+				label={label}
+				placeholder={placeholder}
+				value={value === "" || value == null ? "" : (value as number)}
+				setValue={clearValidationAndSet}
+				error={display.displayError}
+				helpText={display.displayHelpText}
+				readOnly={readOnly}
+				disabled={display.isDisabled}
+				onBlur={handleBlur}
+				formHelperTextSx={display.formHelperTextSx}
+			/>
+		);
+	}
+	if (inputType === InputType.SELECTOR) {
+		return (
+			<SelectorInput
+				fieldName={fieldName}
+				label={label}
+				value={(value as string) ?? ""}
+				setValue={clearValidationAndSet}
+				helpText={display.displayHelpText}
+				error={display.displayError}
+				options={options}
+				readOnly={readOnly}
+				disabled={display.isDisabled}
+				onBlur={handleBlur}
+				formHelperTextSx={display.formHelperTextSx}
+			/>
+		);
+	}
+	if (inputType === InputType.CHECKBOX) {
+		return (
+			<Box onBlur={handleBlur}>
+				<CheckboxInput
+					label={label}
+					checked={Boolean(value)}
+					setChecked={clearValidationAndSet}
+					helpText={display.displayHelpText}
+					readOnly={readOnly}
+					disabled={display.isDisabled}
+					formHelperTextSx={display.formHelperTextSx}
+				/>
+			</Box>
+		);
+	}
+
+	return null;
+}

package/src/components/templatesV2/inputs/primitives/index.ts

@@ -0,0 +1,10 @@
+export { CheckboxInput } from "./CheckboxInput";
+export { NumberInput } from "./NumberInput";
+export { SelectorInput } from "./SelectorInput";
+export { TextInput } from "./TextInput";
+export {
+	TextWithQueryInput,
+	type TextWithQueryInputProps,
+	type TextWithQueryInputType,
+	type TextWithQueryValue,
+} from "./TextWithQueryInput";

package/src/components/templatesV2/inputs/renderers/index.ts

@@ -0,0 +1,2 @@
+export { renderFormControl } from "./renderFormControl";
+export { renderSearchInput } from "./renderSearchInput";