Summary (썸머리)

Va.Summary — HTML5 <summary> 시맨틱 컴포넌트

<details> 컨테이너의 항상 보이는 헤더(제목) 역할을 하는 시맨틱 컴포넌트입니다. Va.Semantic을 상속받아 <summary> 태그로 렌더링됩니다. 사용자가 이 요소를 클릭하면 부모 <details>가 접혔다 펼쳐집니다.

클래스 정보

Va.Summary extends Va.Semantic extends Va.Component
tagName: 'summary'
isContainer: true

기본 사용법

{
    tagName: 'details',
    tags: [{
        tagName: 'summary',
        innerHTML: '자세히 보기'
    },{
        tagName: 'div',
        innerHTML: '펼쳐졌을 때 보이는 상세 내용'
    }]
}

또는 코드로:

let summary = new Va.Summary({
    text: '더 알아보기'
});
detailsComponent.append(summary);

HTML5 <summary>의 의미

<summary>는 HTML5 시맨틱 태그로, <details>의 첫 자식으로 반드시 위치해야 하는 요소입니다.

• 브라우저가 자동으로 클릭 가능한 헤더로 렌더링
• 부모 <details>의 open/close 상태를 토글
• 기본적으로 삼각형 마커(▶ / ▼)가 앞에 붙음 (CSS로 커스터마이징 가능)
• 스크린 리더에서 disclosure widget으로 인식되어 접근성 지원

Va.Details와의 관계 — 중요

VanillaFront에서 Va.Details는 이미 내부적으로 <summary> 요소를 자동 생성합니다 (va_component.js:20186-20188). 따라서:

• Va.Details를 쓸 때는 Va.Summary를 별도로 만들 필요 없음 — title 속성으로 헤더 텍스트를 지정하면 됨
• Va.Summary는 주로 네이티브 <details> 태그 조합에서 또는 직접 disclosure 구조를 커스터마이징할 때 사용

속성

Va.Semantic으로부터 상속:

• innerHTML — HTML 문자열
• text — 순수 텍스트 (자동 이스케이프)
• layout, style, class, hidden 등 공통 속성

내부 속성:

• headerPosition (기본 'top')
• enableChildTags: ['tabItem'] — TabItem 자식 허용

이벤트

Va.Semantic에서 상속받되 추가로 명시적 노출:

• click — 클릭 시 (부모 <details> 토글의 트리거)
• contextmenu — 우클릭 시

메서드

• setText(text) — 텍스트 설정 후 업데이트
• setInnerHTML(html) — HTML 설정 후 업데이트
• Va.Component / Va.Semantic 공통 메서드

내부 구조

<summary>
    <!-- containerElement는 element 자신 -->
    <!-- text 또는 innerHTML이 여기에 들어감 -->
</summary>

Va.Details가 자동 생성하는 <summary>는 다음 구조:

<summary class="header" tabindex="0" elname="header">
    <div elname="title">타이틀</div>
    <button cpname="headerButton"><!-- +/- 아이콘 --></button>
</summary>

사용 시점 — 언제 쓰나

• 네이티브 <details>와 조합 — 프레임워크 확장 없이 순수 HTML5 disclosure UI를 원할 때
• 커스텀 disclosure 위젯 — Va.Details의 아이콘·헤더 구성이 마음에 안 들어 자체 구성이 필요할 때
• 문서 파싱/편집기 — HTML5 문서 표현이 필요한 에디터(예: WYSIWYG)에서 <summary> 태그를 표현

사용하지 말아야 할 때

• 일반적인 접기/펼치기 UI → 대부분 Va.Details가 이미 처리하므로 그쪽 사용
• <details> 밖에 놓는 것 → HTML5 스펙 위반, 브라우저가 예상대로 동작하지 않음
• 일반 헤더 → Va.Header 또는 <h1>~<h6> 사용

자주 쓰는 조합 예시

순수 details + summary 조합

{
    tagName: 'details',
    tags: [{
        tagName: 'summary',
        innerHTML: '<strong>Q. VanillaFront는 무엇인가요?</strong>'
    },{
        tagName: 'div',
        style: { padding: '10px 20px' },
        innerHTML: 'B2B UI Framework입니다.'
    }]
}

커스텀 스타일링

{
    tagName: 'details',
    tags: [{
        tagName: 'summary',
        style: {
            cursor: 'pointer',
            padding: '10px',
            background: 'var(--colorNeutralBackground)',
            fontWeight: 'bold'
        },
        innerHTML: '펼치려면 클릭'
    },{
        tagName: 'div',
        innerHTML: '내용...'
    }]
}

Va.Details와 대비

// Va.Details 사용 (권장, summary 자동 생성)
{ tagName: 'details', title: '자세히', innerHTML: '내용' }

// summary를 직접 지정 (특별한 경우)
{
    tagName: 'details',
    tags: [
        { tagName: 'summary', innerHTML: '<i class="ico_info"></i> 자세히' },
        { tagName: 'div', innerHTML: '내용' }
    ]
}

실전 예시 — 커스텀 헤더가 필요한 disclosure

config(){
    return {
        tagName: 'details',
        style: { border: '1px solid var(--colorNeutralStroke)', borderRadius: '4px' },
        tags: [{
            tagName: 'summary',
            style: {
                listStyle: 'none',
                padding: '12px 16px',
                cursor: 'pointer',
                display: 'flex',
                alignItems: 'center',
                gap: '8px'
            },
            innerHTML: '<i class="ico_settings"></i>고급 설정 <span style="margin-left:auto;color:var(--colorForegroundSecondary)">(선택)</span>'
        },{
            tagName: 'section',
            style: { padding: '16px' },
            tags: [ /* 세부 설정 폼 */ ]
        }]
    };
}

주의사항

• 반드시 <details>의 첫 자식이어야 함 — 다른 위치에 두면 브라우저가 무시하거나 예상 밖 동작
• 한 <details>에 하나만 — 여러 <summary>는 HTML 스펙상 정의되지 않음
• 기본 마커(▶) 숨기기 — list-style: none으로 CSS 제거 가능
• Va.Details와 중복 사용 주의 — Va.Details는 이미 summary를 만드니, 그 안에 또 넣으면 두 개가 될 수 있음
• 접근성 — 스크린 리더가 자동으로 인식하지만, tabindex="0"을 명시하면 더 안정적

대안 비교

상황추천

접기/펼치기 UI (일반)	Va.Details — summary 자동 생성
순수 HTML5 disclosure	Va.Summary + <details> 직접 조합
페이지 상단 헤더	Va.Header
문단 제목	<h1>~<h6>

참고

• API 문서 페이지: https://vanillafront.com/docs.html?theme=light#main#apisummary
• 연관: Va.Semantic(부모), Va.Details(짝을 이루는 컨테이너)