Gnuboard7/docs/frontend/components.md

컴포넌트 개발 규칙

참조: 프론트엔드 가이드 인덱스

---

TL;DR (5초 요약)

1. HTML 태그 직접 사용 금지 (<div> → Div, <button> → Button)
2. 타입: basic (HTML 래핑), composite (조합), layout (배치)
3. 집합 컴포넌트 재사용 우선 (새로 만들기 전 기존 확인)
4. G7Core.t() 함수로 다국어 처리
5. 다크 모드: light/dark variant 함께 지정

---

하위 문서 안내

하위 문서	주요 내용	설명
components-types.md	basic, composite, layout	컴포넌트 타입별 개발 규칙, 재사용 가이드라인
components-patterns.md	순환 의존성, G7Core.t, skipBindingKeys	패턴 및 다국어 처리
components-advanced.md	componentEvent, 아이콘, 체크리스트	이벤트 통신, 아이콘 규칙, 개발 체크리스트

템플릿별 레퍼런스

템플릿 식별자	컴포넌트	핸들러	레이아웃
sirsoft-basic	components.md	handlers.md	layouts.md

sirsoft-admin_basic 은 문서를 그 템플릿이 직접 소유합니다 — templates/_bundled/sirsoft-admin_basic/docs/. 템플릿별 문서 위치는 templates/README.md 를 따릅니다.

---

목차

타입별 개발 규칙 (상세 문서)

1. 핵심 원칙
2. 기본 컴포넌트 (Basic Component)
3. 집합 컴포넌트 (Composite Component)
4. 집합 컴포넌트 재사용 가이드라인
5. 레이아웃 컴포넌트 (Layout Component)

패턴 및 다국어 (상세 문서)

6. 순환 의존성 해결 패턴
7. 다국어 번역 (G7Core.t)
8. skipBindingKeys (바인딩 지연 처리)

고급 기능 (상세 문서)

9. 컴포넌트 간 이벤트 통신 (G7Core.componentEvent)
10. 이벤트 생성 헬퍼
11. 아이콘 사용 규칙 (Font Awesome)
12. Form 자동 바인딩 메타데이터 (bindingType)
13. 컴포넌트 개발 체크리스트

---

핵심 원칙

필수: 기본 컴포넌트 사용 (HTML 태그 직접 사용 금지)
필수: 기본 컴포넌트만 사용 (Div, Button, H2 등)
✅ 필수: 집합 컴포넌트 재사용 우선

→ 상세 문서

---

기능 빠른 참조

컴포넌트 타입 요약

타입	정의	예시
basic	HTML 태그 래핑	Button, Input, Div, Icon, H1, Span
composite	기본 컴포넌트 조합	Card, DataGrid, Modal, Pagination
layout	자식 요소 배치	Container, Grid, Flex, SectionLayout

→ 상세 문서

다국어 처리 (G7Core.t)

// G7Core.t() 번역 함수 참조
const t = (key: string, params?: Record<string, string | number>) =>
  (window as any).G7Core?.t?.(key, params) ?? key;

// 사용
<Button>{t('common.confirm')}</Button>
<Span>{t('admin.users.pagination_info', { from: 1, to: 10, total: 100 })}</Span>

→ 상세 문서

컴포넌트 이벤트 통신

// 이벤트 구독
const unsubscribe = G7Core.componentEvent.on('eventName', callback);

// 이벤트 발생
G7Core.componentEvent.emit('triggerUpload:logo_uploader');

→ 상세 문서

아이콘 사용 (Font Awesome)

import { Icon, IconName } from '../basic/Icon';

<Icon name={IconName.Check} />
<Icon name="fa-solid fa-user" />

주의: Font Awesome Pro 전용 아이콘 사용 금지 (Light, Thin, Duotone)
주의: 다른 아이콘 라이브러리 직접 import 금지

→ 상세 문서

컴포넌트 등록 체크리스트

필수: 새 컴포넌트 생성 시 아래 4개 파일에 등록
□ 컴포넌트 파일 생성: templates/[vendor-template]/src/components/{type}/{Name}.tsx
□ index.ts export 추가: templates/[vendor-template]/src/components/{type}/index.ts
□ components.json 등록: templates/[vendor-template]/components.json
□ 테스트 파일 생성: templates/[vendor-template]/src/components/{type}/__tests__/{Name}.test.tsx

→ 상세 문서

레이아웃 편집기 capability 선언 의무

새 draggable 컴포넌트(레이아웃 편집기 팔레트/캔버스에 노출)는 위 4개 파일에 더해 호스트 템플릿 editor-spec/componentCapabilities.json 에 capability 를 선언해야 편집기에서 "편집 불가(no-editable)"가 되지 않는다. 표시 텍스트/아이콘/select/목록·배열·표 데이터 prop 별로 propControls(속성 탭) / dataProps(데이터 연결) / nodeEditor·canvasOverlay(구조 에디터) / styleControls(스타일 탭) / events(동작 탭) 를 선언한다. 데이터 표면을 가진 컴포넌트가 편집 슬롯도 비대상 allowlist 도 없으면 정적 검사가 차단한다. composite/layout 컴포넌트는 editorAttrs spread + id 패스스루도 필요하다.

상세: editor-spec.md "componentCapabilities" · components-types.md "편집기 attribute 패스스루"

---

관련 문서

• g7core-api.md - G7Core 전역 API 레퍼런스
• 레이아웃 JSON 스키마 - 컴포넌트를 레이아웃 JSON에서 사용하는 방법
• 데이터 바인딩 - props에서 데이터 바인딩 사용법
• sirsoft-admin_basic 컴포넌트 - Admin 컴포넌트 목록
• sirsoft-basic 컴포넌트 - User 컴포넌트 목록 (58개)
• 다크 모드 - 컴포넌트 다크 모드 지원 가이드
• 상태 관리 - 전역/로컬 상태 관리 및 동기화 패턴