HeuJung
6c63536f81
번들 확장 20개 전부에 AGENTS.md · README.md · docs/ 를 채우고, 코어가 들고 있던 확장 소유 문서 두 갈래를 그 확장으로 옮긴다. 번들 템플릿의 컴포넌트· 핸들러·레이아웃 상세와 확장이 구독하는 활동 로그 훅 목록이 그 대상이며, 코어에는 총계와 링크만 남아 확장이 기능을 늘릴 때 코어 문서를 고쳐야 하던 역방향 의존이 사라진다. 전수 완비를 확인하고 강제를 조인다 — 문서 동반 룰을 대상 목록 없는 error 로 승격하고, 검사 스크립트가 문서 미보유를 실패로 올리며, 미채움 마커 baseline 을 0 으로 기록한다. 한쪽만 조이면 "새 확장이 문서 없이 들어와도 초록" 인 상태가 남는데 그 결과는 이상 0건과 구분되지 않는다. 집필 과정에서 드러난 생성기 결함 셋을 함께 고친다. 스케줄 주기 열이 계약 키를 읽지 않아 모든 확장에서 '-' 였고, 네임스페이스를 붙인 핸들러 등록 키가 수집에서 통째로 빠졌으며, README 골격이 폐기된 히어로 배지를 계속 찍어내고 있었다. 셋 다 산출물이 아니라 원천이 틀린 것이라, 가드의 모집단에 생성기 출력 자체를 넣어 다음 확장이 같은 상태로 태어나는 경로를 막는다.
6.8 KiB
6.8 KiB
컴포넌트 개발 규칙
참조: 프론트엔드 가이드 인덱스
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-admin_basic은 문서를 그 템플릿이 직접 소유합니다 — templates/_bundled/sirsoft-admin_basic/docs/. 템플릿별 문서 위치는 templates/README.md 를 따릅니다.
목차
타입별 개발 규칙 (상세 문서)
- 핵심 원칙
- 기본 컴포넌트 (Basic Component)
- 집합 컴포넌트 (Composite Component)
- 집합 컴포넌트 재사용 가이드라인
- 레이아웃 컴포넌트 (Layout Component)
패턴 및 다국어 (상세 문서)
고급 기능 (상세 문서)
- 컴포넌트 간 이벤트 통신 (G7Core.componentEvent)
- 이벤트 생성 헬퍼
- 아이콘 사용 규칙 (Font Awesome)
- Form 자동 바인딩 메타데이터 (bindingType)
- 컴포넌트 개발 체크리스트
핵심 원칙
필수: 기본 컴포넌트 사용 (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 컴포넌트 목록 (확장 소유)
- 다크 모드 - 컴포넌트 다크 모드 지원 가이드
- 상태 관리 - 전역/로컬 상태 관리 및 동기화 패턴