Gnuboard7/docs/frontend/templates/sirsoft-basic/components.md

sirsoft-basic 컴포넌트

템플릿 식별자: sirsoft-basic (type: user, v0.4.16) 관련 문서: 핸들러 | 레이아웃 | 컴포넌트 Props 레퍼런스

---

TL;DR (5초 요약)

1. Basic 26개: HTML 래핑 (Div, Button, Input, Select, Form, A, H1~H4, PasswordInput 등)
2. Composite 27개: UI 패턴 캡슐화 (Header, Footer, Modal, ProductCard, Pagination 등)
3. Layout 5개: 페이지 구조 (Container, Grid, Flex, SectionLayout, ThreeColumnLayout)
4. 사용자(User) 템플릿 전용 — 모듈 레이아웃(user/ 하위)에서 사용
5. features: dark_mode, responsive, multi_language, multi_currency 지원

---

목차

1. 컴포넌트 개요
2. Basic Components (26개)
3. Composite Components (27개)
4. Layout Components (5개)
5. sirsoft-admin_basic과의 차이

---

컴포넌트 개요

타입	개수	설명
Basic	26	HTML 태그 래핑 — 최소 단위 컴포넌트
Composite	27	기본 컴포넌트 조합 — UI 패턴 캡슐화
Layout	5	페이지 구조 정의 — 컨테이너/그리드/플렉스
합계	58

소스: templates/_bundled/sirsoft-basic/components.json 컴포넌트 소스: templates/_bundled/sirsoft-basic/src/components/{basic,composite,layout}/*.tsx

---

Basic Components (26개)

HTML 태그를 래핑하는 최소 단위 컴포넌트입니다.

텍스트/링크

컴포넌트	설명	주요 Props	바인딩
A	앵커/링크	href	-
H1	제목 (h1)	-	-
H2	제목 (h2)	-	-
H3	제목 (h3)	-	-
H4	제목 (h4)	-	-
P	문단	-	-
Span	인라인 텍스트	-	-
Label	라벨	-	-

컨테이너

컴포넌트	설명	주요 Props	바인딩
Div	범용 컨테이너	-	-
Nav	네비게이션 래퍼	-	-
Form	폼 컨테이너	-	-
Header	HTML header 래퍼	-	-
Footer	HTML footer 래퍼	-	-
Hr	수평선	-	-

폼 입력

컴포넌트	설명	주요 Props	바인딩
Input	텍스트 입력	label, error	checkable
Select	선택 박스	label, error	-
Option	Select 내부 옵션	value, disabled	-
Textarea	텍스트 영역	label, error	-
Checkbox	체크박스	label	checked
PasswordInput	비밀번호 입력 (보기/숨기기, 조건 검증, 확인 일치)	label, error, showToggle, showValidation, isConfirmField, confirmTarget, showRules, ...	-
Button	버튼	variant, size	-

미디어

컴포넌트	설명	주요 Props	바인딩
Icon	FontAwesome 아이콘	name	-
Img	이미지	src, alt	-

기타

컴포넌트	설명
Table	HTML table wrapper
Ul	순서 없는 리스트
Li	리스트 아이템

---

Composite Components (27개)

기본 컴포넌트를 조합하여 UI 패턴을 캡슐화한 복합 컴포넌트입니다.

사이트 레이아웃

컴포넌트	설명	주요 Props
Header	사이트 헤더 (로고, 네비게이션, 검색, 사용자 메뉴)	siteName
Footer	사이트 푸터 (저작권, 링크, 소셜)	siteName
MobileNav	모바일 네비게이션 드로어	-

쇼핑몰

컴포넌트	설명	주요 Props
ProductCard	상품 카드 (이미지, 제목, 가격)	product, showDiscount
ProductImageViewer	상품 이미지 뷰어 (메인 + 썸네일 + 라이트박스)	images
QuantitySelector	수량 선택기 (+/- 버튼)	value, min, max

게시판

컴포넌트	설명	주요 Props
PostReactions	게시글 리액션 버튼 그룹	postId, reactions
ExpandableContent	콘텐츠 펼치기/접기 (높이 초과 시 그라데이션)	maxHeight, expandText, collapseText

인증

컴포넌트	설명	주요 Props
SocialLoginButtons	소셜 로그인 버튼 그룹	providers

사용자

컴포넌트	설명	주요 Props
Avatar	사용자 아바타 (이미지 또는 이름 첫 글자)	name, avatar, size, text
AvatarUploader	아바타 이미지 업로드 (원형 UI, 즉시 업로드)	src, fallbackText, size, uploadEndpoint, deleteEndpoint, showDeleteButton, ...
UserInfo	사용자 정보 표시 및 드롭다운	name, userId, subText, isGuest, showDropdown, clickable, ...

에디터/콘텐츠

컴포넌트	설명	주요 Props
HtmlContent	HTML 안전 렌더링 (DOMPurify XSS 방지)	content, text, isHtml, purifyConfig
HtmlEditor	HTML/텍스트 에디터 (WYSIWYG, 미리보기)	name, value, placeholder, isHtml, showPreview, minHeight
RichTextEditor	리치 텍스트 에디터	value, placeholder
ImageGallery	이미지 갤러리 (썸네일 + 메인 이미지)	images

파일/미디어

컴포넌트	설명	주요 Props
FileUploader	파일 업로드	accept, maxSize, multiple

네비게이션/피드백

컴포넌트	설명	주요 Props
TabNavigation	탭 네비게이션 (underline/pills/enclosed)	tabs, activeTabId, variant, onTabChange, hiddenTabIds
Pagination	페이지네이션	currentPage, totalPages, maxVisiblePages, showFirstLast, prevText, nextText

TabNavigation hiddenTabIds: 특정 조건에서 탭을 동적으로 숨길 때 사용합니다. 탭 아이템의 id 배열을 전달하면 해당 탭이 렌더링에서 제외됩니다.

{
  "name": "TabNavigation",
  "props": {
    "tabs": [...],
    "hiddenTabIds": "{{_global.modules?.['sirsoft-ecommerce']?.inquiry?.board_slug ? [] : ['qna']}}"
  }
}

| SearchBar | 검색 바 (자동완성 지원) | name, placeholder, value, showButton, suggestions, showSuggestions | | Modal | 모달 다이얼로그 (ESC, 포커스 트랩) | isOpen, onClose, title, width | | ConfirmDialog | 확인/취소 다이얼로그 | isOpen, onClose, title, message, confirmText, cancelText, ... | | Toast | 토스트 알림 | toasts, position, duration | | ThemeToggle | 테마 전환 토글 (auto/light/dark) | autoText, lightText, darkText |

페이지 전환

컴포넌트	설명	주요 Props
PageTransitionIndicator	페이지 전환 로딩 인디케이터	-
PageTransitionBlur	페이지 전환 시 콘텐츠 블러 오버레이	-
PageSkeleton	동적 스켈레톤 UI 렌더러	components, options

---

Layout Components (5개)

페이지 구조를 정의하는 레이아웃 컴포넌트입니다.

컴포넌트	설명	주요 Props
Container	레이아웃 컨테이너	maxWidth
Flex	Flexbox 레이아웃	direction, gap
Grid	Grid 레이아웃	cols, gap
SectionLayout	섹션 레이아웃 (제목, 부제목, 패딩)	title, subtitle, padding, background
ThreeColumnLayout	3단 레이아웃 (좌/중/우)	leftWidth, centerWidth, rightWidth, gap

---

sirsoft-admin_basic과의 차이

공통 컴포넌트

두 템플릿 모두에 존재하는 컴포넌트:

타입	공통 컴포넌트
Basic	A, Button, Checkbox, Div, Form, H1~H4, Icon, Img, Input, Label, Li, Nav, P, Select, Span, Table, Textarea, Ul
Composite	ConfirmDialog, FileUploader, HtmlContent, HtmlEditor, ImageGallery, Modal, Pagination, ProductCard, SearchBar, TabNavigation, ThemeToggle, Toast
Layout	Container, Flex, Grid, SectionLayout, ThreeColumnLayout

sirsoft-basic 전용 컴포넌트

타입	전용 컴포넌트	설명
Basic	PasswordInput	비밀번호 입력 (보기/숨기기, 검증)
Basic	Header, Footer, Hr	HTML5 시맨틱 태그
Composite	Header, Footer	사이트 헤더/푸터 (composite)
Composite	MobileNav	모바일 드로어 네비게이션
Composite	ProductImageViewer	상품 이미지 뷰어
Composite	QuantitySelector	수량 선택기
Composite	PostReactions	게시글 리액션
Composite	SocialLoginButtons	소셜 로그인
Composite	Avatar, AvatarUploader	아바타 관련
Composite	UserInfo	사용자 정보 드롭다운
Composite	RichTextEditor	리치 텍스트 에디터
Composite	ExpandableContent	콘텐츠 접기/펼치기
Composite	PageTransitionBlur	전환 블러 효과
Composite	PageSkeleton	스켈레톤 UI

sirsoft-admin_basic 전용 컴포넌트 (이 템플릿에 없음)

AdminSidebar, AdminHeader, AdminFooter, PageHeader, DataGrid, CodeEditor, DynamicFieldList, MultilingualInput, TagInput, Toggle, RadioGroup, FormField, SlotContainer, FilterGroup 등 관리자 전용 컴포넌트 39개+

---

관련 문서

• sirsoft-basic 핸들러
• sirsoft-basic 레이아웃
• sirsoft-admin_basic 컴포넌트
• 컴포넌트 개발 규칙
• 컴포넌트 Props 레퍼런스