Details (디테일스)

Va.Details — 접고 펼치는 HTML5 <details> 컴포넌트

타이틀을 클릭하면 본문이 접혔다 펼쳐지는 아코디언형 시맨틱 컴포넌트입니다. HTML5 <details> + <summary> 태그를 기반으로 하며, 열림/닫힘 아이콘과 커스텀 헤더 위치를 지원합니다.

클래스 정보

Va.Details extends Va.Semantic extends Va.Component
tagName: 'details'
isContainer: true

기본 사용법

{
    tagName: 'details',
    title: '더 알아보기',
    open: false,
    tags: [{
        tagName: 'div',
        innerHTML: '숨겨진 상세 내용이 여기에 표시됩니다.'
    }]
}

또는 코드로:

let details = new Va.Details({
    title: '자세히',
    open: true,
    innerHTML: '펼쳐진 상세 내용'
});
parent.append(details);

HTML5 <details>의 의미

<details>는 HTML5 시맨틱 태그로, 필요할 때만 펼쳐 보는 부가 정보를 감쌉니다. <summary> 자식이 항상 보이는 헤더 역할을 하며, 사용자가 클릭하면 나머지 자식이 노출됩니다.

VanillaFront의 Va.Details는 여기에 아이콘 토글 버튼, 헤더 위치(top/bottom), keyboard(Enter/Space) 지원, 커스텀 이벤트를 얹은 확장판입니다.

속성

속성타입기본값설명

title	String	—	헤더에 표시되는 타이틀 텍스트
open	Boolean	false	초기 펼침 상태
headerPosition	String	'top'	'top' 또는 'bottom' — 헤더 위치
openIcon	String	'ico_add_square'	접힌 상태 아이콘
closeIcon	String	'ico_subtract_square'	펼친 상태 아이콘
innerHTML	String	—	본문 HTML
text	String	—	본문 순수 텍스트
focused	Boolean	—	포커스 상태 (readonly로 활용)

이벤트

이벤트발생 시점콜백 인자

expand	펼쳐질 때	(sender, element, evt)
collapse	접힐 때	(sender, element, evt)
click	헤더 클릭 시	(sender, element, evt)

메서드

• expand() — 펼치기
• collapse() — 접기
• setTitle(text) — 타이틀 변경
• setText(text) / setInnerHTML(html) — 본문 변경
• focus() / blur() — 헤더 포커스 제어

내부 구조

<details class="va-detail" va-role="va-detail">
    <summary class="header" tabindex="0" elname="header">
        <div elname="title">타이틀 텍스트</div>
        <button cpname="headerButton"><!-- +/- 토글 아이콘 --></button>
    </summary>
    <div class="body" elname="detail">
        <div class="detail-inner" elname="detailInner" style="overflow:auto">
            <!-- containerElement — 자식 컴포넌트 위치 -->
        </div>
    </div>
</details>

headerPosition: 'bottom'이면 summary가 아래로 이동합니다.

사용 시점 — 언제 쓰나

• FAQ / 도움말 — 질문 목록에서 각 질문을 클릭하면 답변이 펼쳐지는 UI
• 부가 설정 — 기본은 숨겨두고 "고급 옵션" 등을 눌러야 보이는 영역
• 긴 텍스트 요약 — 미리보기만 보이고 "더보기"로 전체 노출
• 디버그/로그 뷰어 — 각 로그 엔트리를 접었다 펼쳤다

사용하지 말아야 할 때

• 여러 항목 중 하나만 열리는 아코디언 → 각 Details를 그룹으로 묶고 이벤트로 제어하거나, 별도 아코디언 컴포넌트 사용
• 탭 인터페이스 → Va.Tab 사용
• 다이얼로그/모달 → Va.Dialog 사용
• 필수로 항상 보여야 할 정보 → 일반 section 사용

자주 쓰는 조합 예시

FAQ 리스트

{
    tagName: 'section',
    layout: 'ds-flex fd-column gap-s',
    tags: [{
        tagName: 'details',
        title: 'VanillaFront는 무엇인가요?',
        innerHTML: 'B2B용 UI Framework로, Vanilla JS ES6 모듈만으로 동작합니다.'
    },{
        tagName: 'details',
        title: '별도 빌드가 필요한가요?',
        innerHTML: '아니요. 브라우저가 ES6 모듈을 직접 로드하므로 No-Build로 동작합니다.'
    },{
        tagName: 'details',
        title: '어떤 컴포넌트가 있나요?',
        innerHTML: '약 120종의 UI 컴포넌트를 제공합니다.'
    }]
}

고급 옵션 접기

{
    tagName: 'form',
    tags: [
        { tagName: 'inputField', label: '이름' },
        { tagName: 'inputField', label: '이메일' },
        {
            tagName: 'details',
            title: '고급 설정',
            open: false,
            tags: [
                { tagName: 'checkboxField', label: '뉴스레터 수신' },
                { tagName: 'checkboxField', label: '알림 수신' }
            ]
        }
    ]
}

이벤트로 상태 감시

{
    tagName: 'details',
    title: '이력 보기',
    onExpand: 'onExpandHistory',
    onCollapse: 'onCollapseHistory',
    tags: [ /* 이력 목록 */ ]
}

// View 안:
onExpandHistory(sender){
    console.log('펼쳐짐');
    this.loadHistory();
}
onCollapseHistory(sender){
    console.log('접힘');
}

실전 예시 — 커스텀 아이콘 + 헤더 위치

{
    tagName: 'details',
    title: '오늘의 팁',
    open: true,
    headerPosition: 'top',
    openIcon: 'ico_chevron_right',
    closeIcon: 'ico_chevron_down',
    style: {
        border: '1px solid var(--colorNeutralStroke)',
        borderRadius: 'var(--sizeRadiusM)',
        padding: 'var(--sizeSpacingM)'
    },
    innerHTML: '<code>Ctrl+Shift+R</code>로 하드 새로고침이 가능합니다.'
}

주의사항

• open() 메서드와 open 속성 이름 충돌 — 소스에 open(open){...} 메서드가 있으나 사실상 속성 대입으로 덮어써지므로 실사용은 expand() / collapse()를 쓰는 것이 안전
• 키보드 지원 — 헤더가 tabindex=0이고 Enter/Space로 토글 가능 (접근성)
• 자식은 detail-inner에 붙음 — containerElement가 detailInner로 설정되어 있어 tags로 넣은 자식은 스크롤 가능한 안쪽 영역에 들어감
• text와 innerHTML 동시 설정 금지 — 텍스트가 우선. 둘 중 하나만 사용
• 여러 개를 그룹으로 쓸 때 아코디언 효과 원하면 각 Details의 expand 이벤트에서 다른 형제 Details를 collapse() 호출해야 함 (기본은 독립적으로 열림)

대안 비교

상황추천

접었다 펼치는 상세 영역	Va.Details
여러 탭 중 하나만 표시	Va.Tab
모달 창	Va.Dialog
항상 보여야 하는 섹션	section / Va.Panel
툴팁	Va.Tooltip

참고

• API 문서 페이지: https://vanillafront.com/docs.html?theme=light#main#apidetails
• 연관: Va.Semantic(부모), Va.Tab(대체 UI)