tomevault-io React Plugin Implementation Skill
역할
당신은 React 기반 @canard/schema-form 플러그인 구현 패턴 전문가입니다.
핵심 책임
- 컴포넌트 구현 패턴: 비제어 컴포넌트 우선 패턴, 최적화 훅 사용법 제시
- test 조건 작성: FormTypeTestObject 및 FormTypeTestFn 작성 가이드
- 성능 최적화: useMemo, useHandle, useCallback 활용 전략
- 플러그인 구조: SchemaFormPlugin 타입 준수 구조 설계
- formTypeInputDefinitions 우선순위: 컴포넌트 배열 순서 최적화
작동 방식
1. 구현 패턴 참조
knowledge/component-patterns.md를 통해 다음 패턴들을 제공합니다:
- 비제어 컴포넌트 패턴 (
defaultValue+onChange) - 제어 컴포넌트 패턴 (실시간 validation 필요 시)
- Array/Object 구조 컴포넌트 특수 처리
- 값 전달 우선순위 (직접 props > context > jsonSchema)
2. 최적화 전략
knowledge/optimization-strategies.md를 활용하여:
useHandle훅으로 이벤트 핸들러 최적화useMemo로 props 연산 캐싱- 불필요한 리렌더링 방지 전략
- Context 구독 최적화
3. Test 조건 작성법
knowledge/test-mapping-conditions.md로:
- 단순 조건: 객체 형태 사용
- 복합 조건: 함수 형태 사용
- 우선순위 순서 결정 (구체적 조건 → 일반적 조건)
제공하는 패턴
기본 컴포넌트 구조
import { useMemo } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema } from '@canard/schema-form';
interface FormTypeInput[Name]Props
extends FormTypeInputPropsWithSchema<ValueType, SchemaType, ContextType>,
ContextType {
// 컴포넌트별 추가 props
}
const FormTypeInput[Name] = ({
// Schema/Node 정보
jsonSchema,
node,
path,
name,
// 상태
required,
disabled,
readOnly,
errors,
// 값
defaultValue,
onChange,
// Context
context,
// 직접 props (Context에서도 올 수 있음)
size: sizeProp,
variant: variantProp,
// 추가 props
placeholder,
}: FormTypeInput[Name]Props) => {
// 1. useMemo로 props 우선순위 적용
const [size, variant, label] = useMemo(() => {
return [
sizeProp || context.size || 'medium',
variantProp || context.variant || 'standard',
jsonSchema.label || jsonSchema.title || name,
];
}, [sizeProp, context, jsonSchema, variantProp, name]);
// 2. useHandle로 이벤트 핸들러 최적화
const handleChange = useHandle((event: ChangeEvent<HTMLInputElement>) => {
onChange(event.target.value);
});
// 3. 비제어 컴포넌트 패턴 사용
return (
<[UILibraryComponent]
id={path}
name={name}
required={required}
disabled={disabled || readOnly}
defaultValue={defaultValue} // ✅ 비제어
size={size}
variant={variant}
placeholder={placeholder || jsonSchema.placeholder}
error={errors.length > 0}
/>
);
};
export const FormTypeInput[Name]Definition = {
Component: FormTypeInput[Name],
test: { type: 'string' }, // 또는 함수 형태
} satisfies FormTypeInputDefinition;
플러그인 구조
// src/index.ts
import type { SchemaFormPlugin } from "@canard/schema-form";
import { FormError } from "./components/FormError";
import { FormGroup } from "./components/FormGroup";
import { FormInput } from "./components/FormInput";
import { FormLabel } from "./components/FormLabel";
import { formatError } from "./components/formatError";
import { formTypeInputDefinitions } from "./formTypeInputs";
export const plugin = {
FormGroup,
FormLabel,
FormInput,
FormError,
formatError,
formTypeInputDefinitions,
} satisfies SchemaFormPlugin;
export type * from "./type";
export * from "./formTypeInputs";
formTypeInputDefinitions 우선순위
// src/formTypeInputs/index.ts
import type { FormTypeInputDefinition } from "@canard/schema-form";
// ⚠️ 순서가 매우 중요! 구체적 조건이 앞에 와야 함
export const formTypeInputDefinitions: FormTypeInputDefinition[] = [
// === Phase 1: 가장 구체적 (format + formType 등) ===
FormTypeInputPasswordDefinition, // type: string, format: password
FormTypeInputTextareaDefinition, // type: string, format: textarea
FormTypeInputSliderDefinition, // type: number, formType: slider
FormTypeInputRadioGroupDefinition, // type: string, formType: radio
// === Phase 2: 중간 (format 또는 formType) ===
FormTypeInputDateDefinition, // type: string, format: date
FormTypeInputTimeDefinition, // type: string, format: time
// === Phase 3: Enum 조건 (함수 형태) ===
FormTypeInputStringEnumDefinition, // type: string, enum exists
FormTypeInputNumberEnumDefinition, // type: number, enum exists
// === Phase 4: 구조 타입 ===
FormTypeInputArrayDefinition, // type: array
FormTypeInputObjectDefinition, // type: object
// === Phase 5: 일반 타입 (마지막) ===
FormTypeInputNumberDefinition, // type: number | integer
FormTypeInputBooleanDefinition, // type: boolean
FormTypeInputStringDefinition, // type: string (가장 일반적 - 마지막!)
];
우선순위 원칙:
- 특수 조건 (format + formType) 먼저
- 중간 조건 (format 또는 formType)
- Enum 조건 (복합 함수)
- 구조 타입 (array, object)
- 일반 타입 (type만) 마지막
특수 패턴
Array 컴포넌트 (ChildNodeComponents 사용)
const FormTypeInputArray = ({
jsonSchema,
path,
ChildNodeComponents, // ✅ canard-form이 제공
context,
}: FormTypeInputArrayProps) => {
return (
<Box>
{ChildNodeComponents.map((ChildComponent, index) => (
<Box key={index} sx={{ mb: 2 }}>
<ChildComponent /> {/* ✅ 자동으로 props 전달됨 */}
</Box>
))}
{/* 추가/제거 버튼만 UI 스타일링 */}
<Button add item */}>Add</Button>
</Box>
);
};
래퍼 컴포넌트 패턴 (DatePicker 등)
const FormTypeInputDate = ({
defaultValue,
onChange,
...props
}: FormTypeInputDateProps) => {
// 값 변환 로직
const dateValue = useMemo(() => {
return defaultValue ? parseISO(defaultValue) : null;
}, [defaultValue]);
const handleChange = useHandle((newDate: Date | null) => {
onChange(newDate ? formatISO(newDate) : '');
});
return (
<LocalizationProvider dateAdapter={AdapterDateFns}>
<DatePicker
value={dateValue}
slotProps={{
textField: {
id: props.path,
name: props.name,
required: props.required,
disabled: props.disabled,
},
}}
/>
</LocalizationProvider>
);
};
성능 최적화 체크리스트
- 비제어 컴포넌트 패턴 적용 (
defaultValue사용) -
useMemo로 props 연산 최적화 -
useHandle로 이벤트 핸들러 메모이제이션 - Context 구독 최소화
- 조건부 렌더링 최적화
- ChildNodeComponents는 직접 렌더링 (props 전파 금지)
제약 조건
- 제어 컴포넌트는 반드시 필요한 경우에만 사용 (실시간 validation, 조건부 렌더링 등)
useHandle훅은@winglet/react-utils에서 importsatisfies FormTypeInputDefinition으로 타입 검증 필수- formTypeInputDefinitions 배열 순서 변경 시 반드시 우선순위 검토
출력 형식
구현 코드 제공 시
## FormTypeInput[Name] 구현
**매핑 조건**: [조건 설명]
**구현 코드**:
[TypeScript 코드]
**최적화 포인트**:
- [최적화 1]
- [최적화 2]
**주의사항**:
- [주의사항 1]
사용 시나리오
시나리오 1: FormTypeInputString 기본 구현
상황: MUI TextField를 사용한 가장 기본적인 문자열 입력 컴포넌트 구현
단계:
Step 1: 타입 정의 및 기본 구조
// src/formTypeInputs/FormTypeInputString.tsx
import { useMemo } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema } from '@canard/schema-form';
import { TextField } from '@mui/material';
import type { TextFieldProps } from '@mui/material';
// 1️⃣ Context 타입 정의 (plugin의 공통 context)
interface MuiFormContext {
size?: 'small' | 'medium' | 'large';
variant?: 'standard' | 'outlined' | 'filled';
}
// 2️⃣ Component Props = FormTypeInputPropsWithSchema + Context + 추가 props
interface FormTypeInputStringProps
extends FormTypeInputPropsWithSchema<string, never, MuiFormContext>,
MuiFormContext {
placeholder?: string;
multiline?: boolean;
rows?: number;
}
// 3️⃣ 컴포넌트 구현
const FormTypeInputString = ({
// Schema/Node 정보
jsonSchema,
node,
path,
name,
// 상태
required,
disabled,
readOnly,
errors,
// 값 (비제어 컴포넌트)
defaultValue,
onChange,
// Context
context,
// 직접 props (우선순위 높음)
size: sizeProp,
variant: variantProp,
// 추가 props
placeholder,
multiline,
rows,
}: FormTypeInputStringProps) => {
// 4️⃣ useMemo로 props 우선순위 적용 (직접 props > context > 기본값)
const [size, variant, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? 'medium',
variantProp ?? context.variant ?? 'outlined',
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [sizeProp, context.size, variantProp, context.variant, jsonSchema.label, jsonSchema.title, name]);
// 5️⃣ 에러 처리
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
// 6️⃣ useHandle로 이벤트 핸들러 최적화
const handleChange = useHandle((event: React.ChangeEvent<HTMLInputElement>) => {
onChange(event.target.value);
});
// 7️⃣ 비제어 컴포넌트 렌더링
return (
<TextField
id={path}
name={name}
label={label}
required={required}
disabled={disabled || readOnly}
defaultValue={defaultValue ?? ''} // ✅ 비제어 컴포넌트
size={size}
variant={variant}
placeholder={placeholder ?? jsonSchema.placeholder}
error={hasError}
helperText={errorMessage ?? jsonSchema.description}
multiline={multiline}
rows={rows}
fullWidth
/>
);
};
// 8️⃣ Definition 객체 (test 조건 포함)
export const FormTypeInputStringDefinition = {
Component: FormTypeInputString,
test: { type: 'string' }, // type이 'string'일 때 매칭
} satisfies FormTypeInputDefinition;
Step 2: 최적화 포인트
// ✅ GOOD: useMemo로 props 연산 캐싱
const [size, variant, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? "medium",
variantProp ?? context.variant ?? "outlined",
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [
sizeProp,
context.size,
variantProp,
context.variant,
jsonSchema.label,
jsonSchema.title,
name,
]);
// ❌ BAD: 매 렌더링마다 연산
const size = sizeProp ?? context.size ?? "medium";
const variant = variantProp ?? context.variant ?? "outlined";
// ✅ GOOD: useHandle로 이벤트 핸들러 메모이제이션
const handleChange = useHandle((event: React.ChangeEvent<HTMLInputElement>) => {
onChange(event.target.value);
});
// ❌ BAD: 매 렌더링마다 새 함수 생성
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
onChange(event.target.value);
};
Step 3: 테스트 작성
// src/formTypeInputs/__tests__/FormTypeInputString.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { FormTypeInputString } from '../FormTypeInputString';
describe('FormTypeInputString', () => {
it('renders with defaultValue', () => {
render(
<FormTypeInputString
jsonSchema={{ type: 'string' }}
path="test"
name="test"
defaultValue="initial value"
required={false}
disabled={false}
readOnly={false}
errors={[]}
context={{}}
/>
);
expect(screen.getByDisplayValue('initial value')).toBeInTheDocument();
});
it('calls onChange when user types', async () => {
const
const user = userEvent.setup();
render(
<FormTypeInputString
jsonSchema={{ type: 'string' }}
path="test"
name="test"
required={false}
disabled={false}
readOnly={false}
errors={[]}
context={{}}
/>
);
await user.type(screen.getByRole('textbox'), 'hello');
expect(onChange).toHaveBeenCalled();
});
});
결과: 기본 문자열 입력 컴포넌트 완성, 비제어 패턴으로 성능 최적화
시나리오 2: FormTypeInputDate (값 변환 패턴)
상황: MUI DatePicker를 사용한 날짜 입력 컴포넌트, ISO 8601 문자열 ↔ Date 객체 변환 필요
단계:
Step 1: 날짜 변환 로직 구현
// src/formTypeInputs/FormTypeInputDate.tsx
import { useMemo } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema } from '@canard/schema-form';
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
import { parseISO, formatISO } from 'date-fns';
import type { MuiFormContext } from '../type';
interface FormTypeInputDateProps
extends FormTypeInputPropsWithSchema<string, never, MuiFormContext>,
MuiFormContext {
minDate?: string;
maxDate?: string;
}
const FormTypeInputDate = ({
jsonSchema,
path,
name,
required,
disabled,
readOnly,
errors,
defaultValue, // ⚠️ ISO 8601 문자열 (예: "2024-01-15T00:00:00.000Z")
onChange, // ⚠️ ISO 8601 문자열로 전달해야 함
context,
size: sizeProp,
variant: variantProp,
minDate,
maxDate,
}: FormTypeInputDateProps) => {
// 1️⃣ ISO 문자열 → Date 객체 변환
const dateValue = useMemo(() => {
if (!defaultValue) return null;
try {
return parseISO(defaultValue);
} catch {
return null;
}
}, [defaultValue]);
// 2️⃣ minDate, maxDate도 변환
const [minDateObj, maxDateObj] = useMemo(() => {
return [
minDate ? parseISO(minDate) : undefined,
maxDate ? parseISO(maxDate) : undefined,
];
}, [minDate, maxDate]);
// 3️⃣ Date 객체 → ISO 문자열 변환 핸들러
const handleChange = useHandle((newDate: Date | null) => {
if (newDate === null) {
onChange('');
return;
}
try {
const isoString = formatISO(newDate);
onChange(isoString);
} catch {
onChange('');
}
});
const [size, variant, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? 'medium',
variantProp ?? context.variant ?? 'outlined',
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [sizeProp, context.size, variantProp, context.variant, jsonSchema.label, jsonSchema.title, name]);
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
// 4️⃣ DatePicker 렌더링
return (
<LocalizationProvider dateAdapter={AdapterDateFns}>
<DatePicker
label={label}
value={dateValue} // ✅ Date 객체
// ✅ Date 객체 받아서 ISO 문자열로 변환
minDate={minDateObj}
maxDate={maxDateObj}
disabled={disabled || readOnly}
slotProps={{
textField: {
id: path,
name: name,
required: required,
size: size,
variant: variant,
error: hasError,
helperText: errorMessage ?? jsonSchema.description,
fullWidth: true,
},
}}
/>
</LocalizationProvider>
);
};
// 5️⃣ Definition 객체 (format: 'date' 조건)
export const FormTypeInputDateDefinition = {
Component: FormTypeInputDate,
test: { type: 'string', format: 'date' }, // type: string + format: date
} satisfies FormTypeInputDefinition;
Step 2: 에러 처리 및 유효성 검증
// date-fns의 isValid 사용
import { parseISO, formatISO, isValid } from "date-fns";
const handleChange = useHandle((newDate: Date | null) => {
if (newDate === null) {
onChange("");
return;
}
// ✅ Date 유효성 검증
if (!isValid(newDate)) {
console.warn("Invalid date:", newDate);
onChange("");
return;
}
try {
const isoString = formatISO(newDate);
onChange(isoString);
} catch (error) {
console.error("Date conversion error:", error);
onChange("");
}
});
Step 3: 타임존 처리 (선택)
// UTC 고정 변환이 필요한 경우
import { parseISO, formatISO } from "date-fns";
import { zonedTimeToUtc, utcToZonedTime } from "date-fns-tz";
const handleChange = useHandle((newDate: Date | null) => {
if (newDate === null) {
onChange("");
return;
}
// 사용자 로컬 시간 → UTC 변환
const utcDate = zonedTimeToUtc(
newDate,
Intl.DateTimeFormat().resolvedOptions().timeZone,
);
const isoString = formatISO(utcDate);
onChange(isoString);
});
결과: ISO 8601 문자열 ↔ Date 객체 변환이 완벽히 처리된 DatePicker 컴포넌트
주의사항:
@canard/schema-form은 항상 ISO 8601 문자열로 값을 주고받음- Date 객체는 컴포넌트 내부에서만 사용, onChange에는 반드시 문자열 전달
date-fns의parseISO,formatISO사용 권장 (타임존 안전)
시나리오 3: FormTypeInputStringEnum (함수 형태 test 조건)
상황: Enum 값을 가진 문자열을 Select 또는 RadioGroup으로 표시
단계:
Step 1: 복합 조건 test 함수 작성
// src/formTypeInputs/FormTypeInputStringEnum.tsx
import { useMemo } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema, FormTypeTestFn } from '@canard/schema-form';
import { FormControl, FormLabel, RadioGroup, FormControlLabel, Radio, FormHelperText } from '@mui/material';
import type { MuiFormContext } from '../type';
interface FormTypeInputStringEnumProps
extends FormTypeInputPropsWithSchema<string, never, MuiFormContext>,
MuiFormContext {}
const FormTypeInputStringEnum = ({
jsonSchema,
path,
name,
required,
disabled,
readOnly,
errors,
defaultValue,
onChange,
context,
size: sizeProp,
}: FormTypeInputStringEnumProps) => {
// 1️⃣ enum 값 추출 (jsonSchema.enum은 배열)
const enumValues = useMemo(() => {
return jsonSchema.enum as string[] ?? [];
}, [jsonSchema.enum]);
// 2️⃣ enum 라벨 매핑 (enumLabels가 있으면 사용)
const enumLabels = useMemo(() => {
if (jsonSchema.enumLabels) {
return jsonSchema.enumLabels as string[];
}
// enumLabels가 없으면 enum 값 그대로 사용
return enumValues;
}, [jsonSchema.enumLabels, enumValues]);
const handleChange = useHandle((event: React.ChangeEvent<HTMLInputElement>) => {
onChange(event.target.value);
});
const [size, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? 'medium',
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [sizeProp, context.size, jsonSchema.label, jsonSchema.title, name]);
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
// 3️⃣ RadioGroup 렌더링
return (
<FormControl error={hasError} required={required} disabled={disabled || readOnly} size={size}>
<FormLabel id={`${path}-label`}>{label}</FormLabel>
<RadioGroup
aria-labelledby={`${path}-label`}
name={name}
defaultValue={defaultValue ?? ''}
>
{enumValues.map((value, index) => (
<FormControlLabel
key={value}
value={value}
control={<Radio />}
label={enumLabels[index] ?? value}
/>
))}
</RadioGroup>
{(hasError || jsonSchema.description) && (
<FormHelperText>{errorMessage ?? jsonSchema.description}</FormHelperText>
)}
</FormControl>
);
};
// 4️⃣ 함수 형태 test 조건 (복합 조건)
const testStringEnum: FormTypeTestFn = ({ type, jsonSchema }) => {
// type이 'string'이고 enum이 있는 경우에만 true
return (
type === 'string' &&
Array.isArray(jsonSchema.enum) &&
jsonSchema.enum.length > 0
);
};
export const FormTypeInputStringEnumDefinition = {
Component: FormTypeInputStringEnum,
test: testStringEnum, // ✅ 함수 형태
} satisfies FormTypeInputDefinition;
Step 2: Select 버전 (대안)
// Select를 사용하는 버전 (많은 옵션일 때 유리)
import { FormControl, InputLabel, Select, MenuItem, FormHelperText } from '@mui/material';
const FormTypeInputStringEnumSelect = ({
jsonSchema,
path,
name,
required,
disabled,
readOnly,
errors,
defaultValue,
onChange,
context,
size: sizeProp,
variant: variantProp,
}: FormTypeInputStringEnumProps) => {
const enumValues = useMemo(() => {
return jsonSchema.enum as string[] ?? [];
}, [jsonSchema.enum]);
const enumLabels = useMemo(() => {
if (jsonSchema.enumLabels) {
return jsonSchema.enumLabels as string[];
}
return enumValues;
}, [jsonSchema.enumLabels, enumValues]);
const handleChange = useHandle((event: SelectChangeEvent<string>) => {
onChange(event.target.value);
});
const [size, variant, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? 'medium',
variantProp ?? context.variant ?? 'outlined',
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [sizeProp, context.size, variantProp, context.variant, jsonSchema.label, jsonSchema.title, name]);
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
return (
<FormControl error={hasError} required={required} disabled={disabled || readOnly} size={size} fullWidth>
<InputLabel id={`${path}-label`}>{label}</InputLabel>
<Select
labelId={`${path}-label`}
id={path}
name={name}
label={label}
defaultValue={defaultValue ?? ''}
variant={variant}
>
{enumValues.map((value, index) => (
<MenuItem key={value} value={value}>
{enumLabels[index] ?? value}
</MenuItem>
))}
</Select>
{(hasError || jsonSchema.description) && (
<FormHelperText>{errorMessage ?? jsonSchema.description}</FormHelperText>
)}
</FormControl>
);
};
Step 3: 선택 기준
// formTypeInputDefinitions 배열에서 조건 기반 선택
export const formTypeInputDefinitions: FormTypeInputDefinition[] = [
// === Phase 1: 가장 구체적 ===
FormTypeInputPasswordDefinition, // type: string, format: password
// === Phase 3: Enum 조건 (함수 형태) ===
// ⚠️ 순서 주의: 구체적 조건이 먼저 와야 함
// Enum이 4개 이하 → RadioGroup
{
Component: FormTypeInputStringEnum,
test: ({ type, jsonSchema }) =>
type === "string" &&
Array.isArray(jsonSchema.enum) &&
jsonSchema.enum.length > 0 &&
jsonSchema.enum.length <= 4,
},
// Enum이 5개 이상 → Select
{
Component: FormTypeInputStringEnumSelect,
test: ({ type, jsonSchema }) =>
jsonSchematype === "string" &&
Array.isArray(jsonSchema.enum) &&
jsonSchema.enum.length > 4,
},
// === Phase 5: 일반 타입 (마지막) ===
FormTypeInputStringDefinition, // type: string (가장 일반적 - 마지막!)
];
결과: Enum 값의 개수에 따라 RadioGroup과 Select를 자동 선택하는 컴포넌트
주의사항:
- test 함수는 복합 조건을 검사할 때 사용
- 더 구체적인 조건이 앞에 와야 함 (RadioGroup → Select → String 순서)
enumLabels를 사용해 사용자 친화적 라벨 제공 가능
시나리오 4: FormTypeInputArray (ChildNodeComponents 패턴)
상황: 배열 타입 입력, ChildNodeComponents를 활용한 동적 렌더링
단계:
Step 1: ChildNodeComponents 활용 패턴
// src/formTypeInputs/FormTypeInputArray.tsx
import { useMemo, useState } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema } from '@canard/schema-form';
import { Box, Button, IconButton, Paper, Typography } from '@mui/material';
import AddIcon from '@mui/icons-material/Add';
import DeleteIcon from '@mui/icons-material/Delete';
import type { MuiFormContext } from '../type';
interface FormTypeInputArrayProps
extends FormTypeInputPropsWithSchema<any[], never, MuiFormContext>,
MuiFormContext {
// ⚠️ ChildNodeComponents는 FormTypeInputPropsWithSchema에서 제공
}
const FormTypeInputArray = ({
jsonSchema,
node,
path,
name,
required,
disabled,
readOnly,
errors,
defaultValue,
onChange,
context,
ChildNodeComponents, // ✅ @canard/schema-form이 제공하는 자식 컴포넌트 배열
size: sizeProp,
}: FormTypeInputArrayProps) => {
// 1️⃣ ChildNodeComponents는 현재 배열 값에 따라 자동으로 생성됨
// 각 ChildComponent는 이미 모든 props를 받은 상태
const [size, label] = useMemo(() => {
return [
sizeProp ?? context.size ?? 'medium',
jsonSchema.label ?? jsonSchema.title ?? name,
];
}, [sizeProp, context.size, jsonSchema.label, jsonSchema.title, name]);
// 2️⃣ 아이템 추가 핸들러
const handleAdd = useHandle(() => {
const currentValue = node.value ?? [];
const newValue = [...currentValue, undefined]; // undefined로 초기화
onChange(newValue);
});
// 3️⃣ 아이템 제거 핸들러
const handleRemove = useHandle((index: number) => {
const currentValue = node.value ?? [];
const newValue = currentValue.filter((_, i) => i !== index);
onChange(newValue);
});
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
// 4️⃣ 렌더링: ChildNodeComponents를 직접 렌더링
return (
<Box>
<Typography variant="h6" gutterBottom>
{label}
{required && <span style={{ color: 'red' }}> *</span>}
</Typography>
{jsonSchema.description && (
<Typography variant="body2" color="text.secondary" gutterBottom>
{jsonSchema.description}
</Typography>
)}
{/* ✅ ChildNodeComponents 렌더링 */}
{ChildNodeComponents && ChildNodeComponents.length > 0 ? (
ChildNodeComponents.map((ChildComponent, index) => (
<Paper key={index} sx={{ p: 2, mb: 2, position: 'relative' }}>
<Box sx={{ pr: 6 }}>
{/* ✅ ChildComponent는 이미 모든 props를 받은 상태 */}
<ChildComponent />
</Box>
{/* 삭제 버튼 */}
{!disabled && !readOnly && (
<IconButton
aria-label="delete"
=> handleRemove(index)}
sx={{ position: 'absolute', top: 8, right: 8 }}
size={size}
>
<DeleteIcon />
</IconButton>
)}
</Paper>
))
) : (
<Typography variant="body2" color="text.secondary">
아이템이 없습니다. "추가" 버튼을 눌러 아이템을 추가하세요.
</Typography>
)}
{/* 추가 버튼 */}
{!disabled && !readOnly && (
<Button
variant="outlined"
startIcon={<AddIcon />}
size={size}
>
추가
</Button>
)}
{/* 에러 메시지 */}
{hasError && (
<Typography variant="body2" color="error" sx={{ mt: 1 }}>
{errorMessage}
</Typography>
)}
</Box>
);
};
// 5️⃣ Definition 객체
export const FormTypeInputArrayDefinition = {
Component: FormTypeInputArray,
test: { type: 'array' },
} satisfies FormTypeInputDefinition;
Step 2: ChildNodeComponents 주의사항
// ❌ WRONG: ChildComponent에 props 전달 시도
{ChildNodeComponents.map((ChildComponent, index) => (
<ChildComponent
key={index}
// ❌ 이렇게 props를 전달하면 안 됨!
value={someValue}
/>
))}
// ✅ CORRECT: ChildComponent는 그대로 렌더링
{ChildNodeComponents.map((ChildComponent, index) => (
<Box key={index}>
{/* ✅ ChildComponent는 이미 모든 props를 받은 상태 */}
<ChildComponent />
</Box>
))}
중요 개념:
ChildNodeComponents는@canard/schema-form이 자동으로 생성한 컴포넌트 배열- 각
ChildComponent는 이미path,jsonSchema,value,onChange등 모든 props를 받은 상태 - FormTypeInputArray는 UI 레이아웃만 담당, 값 관리는 canard-form이 처리
Step 3: 복잡한 배열 아이템 예시
// JSON Schema 예시
const schema = {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string", label: "이름" },
age: { type: "number", label: "나이" },
email: { type: "string", format: "email", label: "이메일" },
},
},
};
// ChildNodeComponents는 자동으로 각 object의 FormTypeInputObject를 생성
// FormTypeInputObject는 다시 name, age, email의 FormTypeInput들을 렌더링
// → 완전히 자동화된 중첩 렌더링
결과: 배열 아이템 추가/제거 UI만 구현하면 되는 간단한 Array 컴포넌트
주의사항:
- ChildNodeComponents에 절대 props 전달 금지
- 값 관리는 onChange로 전체 배열 업데이트
- 삭제 시 filter 사용, 추가 시 spread 사용
시나리오 5: FormTypeInputFileUpload (onFileAttach 통합)
상황: 파일 업로드 기능, onFileAttach 콜백 통합
단계:
Step 1: onFileAttach 타입 정의
// src/type.ts
export interface MuiFormContext {
size?: "small" | "medium" | "large";
variant?: "standard" | "outlined" | "filled";
// ✅ onFileAttach 콜백 정의
onFileAttach?: (file: File) => Promise<string>; // 파일 업로드 후 URL 반환
}
Step 2: FileUpload 컴포넌트 구현
// src/formTypeInputs/FormTypeInputFileUpload.tsx
import { useState, useRef } from 'react';
import { useHandle } from '@winglet/react-utils';
import type { FormTypeInputPropsWithSchema } from '@canard/schema-form';
import { Box, Button, Typography, LinearProgress, IconButton, Chip } from '@mui/material';
import CloudUploadIcon from '@mui/icons-material/CloudUpload';
import DeleteIcon from '@mui/icons-material/Delete';
import type { MuiFormContext } from '../type';
interface FormTypeInputFileUploadProps
extends FormTypeInputPropsWithSchema<string, never, MuiFormContext>,
MuiFormContext {
accept?: string; // 예: "image/*", ".pdf,.doc"
maxSize?: number; // 바이트 단위
}
const FormTypeInputFileUpload = ({
jsonSchema,
path,
name,
required,
disabled,
readOnly,
errors,
defaultValue, // ⚠️ 파일 URL 문자열
onChange, // ⚠️ 파일 URL 문자열로 전달
context,
size: sizeProp,
accept,
maxSize = 10 * 1024 * 1024, // 기본 10MB
}: FormTypeInputFileUploadProps) => {
const [uploading, setUploading] = useState(false);
const [uploadProgress, setUploadProgress] = useState(0);
const inputRef = useRef<HTMLInputElement>(null);
const label = jsonSchema.label ?? jsonSchema.title ?? name;
const hasError = errors.length > 0;
const errorMessage = hasError ? errors[0].message : undefined;
// 1️⃣ 파일 선택 핸들러
const handleFileSelect = useHandle(async (event: React.ChangeEvent<HTMLInputElement>) => {
const file = event.target.files?.[0];
if (!file) return;
// 2️⃣ 파일 크기 검증
if (file.size > maxSize) {
alert(`파일 크기는 ${maxSize / 1024 / 1024}MB를 초과할 수 없습니다.`);
return;
}
// 3️⃣ onFileAttach 콜백 호출 (context에서 제공)
if (!context.onFileAttach) {
console.error('onFileAttach callback is not provided in context');
alert('파일 업로드 기능이 설정되지 않았습니다.');
return;
}
try {
setUploading(true);
setUploadProgress(0);
// 업로드 진행 시뮬레이션 (실제로는 onFileAttach 내부에서 처리)
const progressInterval = setInterval(() => {
setUploadProgress((prev) => Math.min(prev + 10, 90));
}, 200);
// 4️⃣ 파일 업로드 (URL 반환)
const fileUrl = await context.onFileAttach(file);
clearInterval(progressInterval);
setUploadProgress(100);
// 5️⃣ onChange로 URL 전달
onChange(fileUrl);
// 리셋
setTimeout(() => {
setUploading(false);
setUploadProgress(0);
}, 500);
} catch (error) {
console.error('File upload error:', error);
alert('파일 업로드 중 오류가 발생했습니다.');
setUploading(false);
setUploadProgress(0);
}
// input 리셋
if (inputRef.current) {
inputRef.current.value = '';
}
});
// 6️⃣ 파일 삭제 핸들러
const handleDelete = useHandle(() => {
onChange('');
});
// 7️⃣ 업로드 버튼 클릭
const handleButtonClick = useHandle(() => {
inputRef.current?.click();
});
return (
<Box>
<Typography variant="body1" gutterBottom>
{label}
{required && <span style={{ color: 'red' }}> *</span>}
</Typography>
{jsonSchema.description && (
<Typography variant="body2" color="text.secondary" gutterBottom>
{jsonSchema.description}
</Typography>
)}
{/* Hidden file input */}
<input
ref={inputRef}
type="file"
accept={accept ?? jsonSchema.accept}
style={{ display: 'none' }}
disabled={disabled || readOnly || uploading}
/>
{/* Upload button or file info */}
{defaultValue ? (
<Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
<Chip
label={defaultValue.split('/').pop() ?? 'Uploaded file'}
&& !readOnly ? handleDelete : undefined}
deleteIcon={<DeleteIcon />}
color="primary"
variant="outlined"
/>
<Button
variant="text"
size="small"
=> window.open(defaultValue, '_blank')}
>
보기
</Button>
</Box>
) : (
<Button
variant="outlined"
startIcon={<CloudUploadIcon />}
disabled={disabled || readOnly || uploading}
size={sizeProp ?? context.size ?? 'medium'}
>
{uploading ? '업로드 중...' : '파일 선택'}
</Button>
)}
{/* Upload progress */}
{uploading && (
<Box sx={{ mt: 1 }}>
<LinearProgress variant="determinate" value={uploadProgress} />
</Box>
)}
{/* Error message */}
{hasError && (
<Typography variant="body2" color="error" sx={{ mt: 1 }}>
{errorMessage}
</Typography>
)}
</Box>
);
};
// 8️⃣ Definition 객체
export const FormTypeInputFileUploadDefinition = {
Component: FormTypeInputFileUpload,
test: { type: 'string', format: 'file' }, // format: 'file'
} satisfies FormTypeInputDefinition;
Step 3: onFileAttach 구현 예시 (사용자 측)
// App.tsx에서 SchemaForm 사용
import { SchemaForm } from '@canard/schema-form';
import { plugin as muiPlugin } from '@canard/schema-form-mui-plugin';
const App = () => {
// onFileAttach 구현 (예: AWS S3 업로드)
const handleFileAttach = async (file: File): Promise<string> => {
// 1. FormData 생성
const formData = new FormData();
formData.append('file', file);
// 2. 서버에 업로드
const response = await fetch('/api/upload', {
method: 'POST',
body: formData,
});
if (!response.ok) {
throw new Error('Upload failed');
}
// 3. 서버에서 반환한 파일 URL
const data = await response.json();
return data.fileUrl; // 예: "https://s3.amazonaws.com/bucket/file.jpg"
};
return (
<SchemaForm
schema={schema}
plugin={muiPlugin}
context={{
size: 'medium',
variant: 'outlined',
onFileAttach: handleFileAttach, // ✅ context로 전달
}}
/>
);
};
Step 4: 다중 파일 업로드 (확장)
// 다중 파일 업로드 버전
interface FormTypeInputMultiFileUploadProps
extends FormTypeInputPropsWithSchema<string[], never, MuiFormContext>,
MuiFormContext {
accept?: string;
maxSize?: number;
maxFiles?: number;
}
const FormTypeInputMultiFileUpload = ({
defaultValue, // string[] (URL 배열)
onChange, // (urls: string[]) => void
context,
maxFiles = 5,
// ... 기타 props
}: FormTypeInputMultiFileUploadProps) => {
const handleFileSelect = useHandle(
async (event: React.ChangeEvent<HTMLInputElement>) => {
const files = Array.from(event.target.files ?? []);
// 파일 개수 검증
if ((defaultValue?.length ?? 0) + files.length > maxFiles) {
alert(`최대 ${maxFiles}개의 파일만 업로드 가능합니다.`);
return;
}
if (!context.onFileAttach) {
alert("파일 업로드 기능이 설정되지 않았습니다.");
return;
}
try {
setUploading(true);
// 병렬 업로드
const uploadPromises = files.map((file) => context.onFileAttach!(file));
const newUrls = await Promise.all(uploadPromises);
// 기존 URL + 새 URL
const allUrls = [...(defaultValue ?? []), ...newUrls];
onChange(allUrls);
setUploading(false);
} catch (error) {
console.error("Multi-file upload error:", error);
alert("파일 업로드 중 오류가 발생했습니다.");
setUploading(false);
}
},
);
// ... 렌더링 (Chip 배열로 표시)
};
결과: 파일 업로드 기능이 완벽히 통합된 컴포넌트, context를 통한 콜백 주입 패턴
주의사항:
onFileAttach는 반드시 context로 제공해야 함- 파일 업로드는 비동기이므로 loading 상태 관리 필수
- 파일 URL은 문자열로 onChange에 전달
- 다중 파일은 string[] 타입 사용
다음 단계 연계
- 구현 완료 후
dependency-management스킬로 package.json 설정 - UI 라이브러리 호환성 검증은
ui-plugin-guidelines스킬 참조
에러 처리
error_handling:
severity_high:
conditions:
- 타입 정의 파일 없음 (types/index.d.ts)
- React 미설치
- @canard/schema-form 패키지 미설치
- UI 라이브러리 미설치 (MUI, Ant Design 등)
- 컴포넌트 빌드 실패 (심각한 구문 오류)
action: |
❌ 치명적 오류 - 컴포넌트 구현 중단
→ 타입 파일 확인: ls types/index.d.ts
→ React 설치: yarn add react react-dom
→ @canard/schema-form 설치: yarn add @canard/schema-form
→ UI 라이브러리 설치: yarn add @mui/material (예시)
→ 빌드 검증: yarn build
→ 재실행: 필수 패키지 설치 후 구현 재시도
examples:
- condition: "타입 파일 없음"
message: "❌ 오류: types/index.d.ts를 찾을 수 없습니다"
recovery: "canard-type-system 먼저 실행하여 타입 정의 생성"
- condition: "UI 라이브러리 미설치"
message: "❌ 오류: @mui/material 패키지를 찾을 수 없습니다"
recovery: "설치: yarn add @mui/material @emotion/react @emotion/styled"
severity_medium:
conditions:
- 컴포넌트 타입 추론 실패
- Props 검증 누락
- UI 라이브러리 컴포넌트 매핑 불명확
- 성능 최적화 자동 적용 실패 (memo, useMemo)
- Storybook args 생성 실패
action: |
⚠️ 경고 - 기본 구현으로 진행
1. 타입: any로 fallback (수동 수정 권장)
2. Props 검증: PropTypes 생략
3. UI 컴포넌트: 기본 HTML 요소 사용
4. 성능 최적화: 수동 적용 권장
5. Storybook: 기본 args만 생성
6. 구현 파일에 경고 추가:
// ⚠️ WARNING: {warning_description}
// → {action_required}
fallback_values:
component_type: "any"
ui_component: "input" # 기본 HTML
optimization: "none (apply manually)"
examples:
- condition: "타입 추론 실패"
message: "⚠️ 경고: FormTypeInput Props 타입을 추론할 수 없습니다"
fallback: "any로 대체 → 수동으로 FormTypeInputProps<string> 지정"
- condition: "UI 컴포넌트 매핑 불명확"
message: "⚠️ 경고: MUI TextField를 자동으로 매핑할 수 없습니다"
fallback: "기본 <input> 사용 → 수동으로 <TextField> 변경"
severity_low:
conditions:
- 접근성 속성 자동 생성 실패
- 스타일링 가이드 위반 (경미한)
- JSDoc 주석 누락
- import 순서 비표준
action: |
ℹ️ 정보: 최적화 제안 - 자동 또는 수동 개선
→ 접근성: aria-* 속성 추가 제안
→ 스타일: Prettier 자동 수정
→ JSDoc: 주석 추가 제안
→ import: ESLint auto-fix
examples:
- condition: "접근성 속성 없음"
auto_handling: "aria-label, aria-describedby 추가 제안"
- condition: "import 순서"
auto_handling: "ESLint --fix로 자동 정렬"
Best Practice: 비제어 컴포넌트 우선, 성능 최적화 항상 고려 Integration: 타입 시스템 기반 구현, 가이드라인 준수
Converted and distributed by TomeVault — claim your Tome and manage your conversions.