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

Basic — 컴포넌트

템플릿이 제공하는 컴포넌트 · 진입점: AGENTS.md

제공 컴포넌트

컴포넌트 79개 (루트: src/components).

분류	개수
basic	38개
composite	36개
layout	5개

세 분류는 "얼마나 조합됐는가" 로 나뉩니다 — basic 은 HTML 태그를 그대로 래핑한 최소 단위 (Div→<div>), composite 는 basic 을 조합해 UI 패턴을 캡슐화한 것(Header 가 로고·네비· 검색·사용자 메뉴를 감싸는 식), layout 은 페이지 구조(Container/Grid/Flex)입니다. 새 컴포넌트는 이 구분에 맞는 디렉토리(src/components/{basic,composite,layout}/)에 넣어야 components.json 카탈로그와 editor-spec.json 팔레트 분류가 어긋나지 않습니다.

이 템플릿은 방문자 화면 전용이라 관리자 템플릿(sirsoft-admin_basic)과 컴포넌트 구성이 크게 다릅니다. DataGrid · AdminSidebar · MultilingualInput 같은 관리 도구가 없고, 대신 ProductCard · ProductImageViewer · QuantitySelector · PostReactions · MobileNav · SocialLoginButtons 처럼 상점·게시판·인증 화면에 필요한 것들이 있습니다. 모듈이 방문자 화면을 그리지 않고 API 만 제공하는 구조(게시판·이커머스 모두 레이아웃이 전부 admin 그룹) 이므로, 방문자가 보는 커머스·게시판 UI 는 사실상 이 템플릿의 컴포넌트가 전부입니다.

위 개수는 코드에서 실측되므로 시간이 지나면 달라집니다 — 이 문서에 구체적 개수를 하드코딩하지 않습니다. 정확한 전체 목록·Props 는 코어의 컴포넌트 Props 레퍼런스를 따르며, 이 문서는 "이 템플릿에서만" 유효한 것을 다룹니다.

이관 원문 상세

아래는 코어 docs/frontend/templates/sirsoft-basic/components.md 에 있던 원문을 이 문서로 옮긴 것입니다(#601). 이관 시점 그대로 보존하되, 코드가 SSoT 인 값과 어긋나는 부분에는 정정 주석을 달았습니다 — 실측 총계는 위 「제공 컴포넌트」 블록이 SSoT 입니다.

sirsoft-basic 컴포넌트

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

정정(#601): 위 버전(v0.4.16)은 이관 시점 문서 값입니다. 현재 버전은 template.json 이 SSoT 입니다.

---

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)
   (정정(#601): 개수는 이관 시점 값 — 실측은 위 「제공 컴포넌트」 블록이 SSoT)
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과의 차이

---

컴포넌트 개요

정정(#601): 아래 개수는 이관 시점 문서 값입니다. 코드 실측은 basic 38 · composite 36 · layout 5 = 79종이며 위 「제공 컴포넌트」 블록이 SSoT 입니다. 아래 목록에 없는 컴포넌트가 있습니다(basic 의 Code · FileInput · I · Ol · Optgroup · Section · Svg · Tbody · Td · Th · Thead · Tr, composite 의 BrandMark · NotificationCenter · PageLoading · SlotContainer 등).

타입	개수	설명
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개)

정정(#601): 제목의 개수는 이관 시점 문서 값입니다(코드 실측 38종). 목록 자체는 원문 그대로입니다.

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개)

정정(#601): 제목의 개수는 이관 시점 문서 값입니다(코드 실측 36종). 목록 자체는 원문 그대로입니다.

기본 컴포넌트를 조합하여 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개+

정정(#601): SlotContainer 는 이 템플릿에도 있습니다(src/components/composite/SlotContainer.tsx). 나머지 항목은 이관 시점 그대로입니다.

---

관련 문서

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