@designbasekorea/ui-wc 0.8.1 → 0.8.3

package/dist/index.d.ts

@@ -1,3 +1,275 @@
+import { BadgeVariant, BadgeType, TIME_PICKER_FORMATS, DOWNLOAD_PROGRESS_STATUSES, DOWNLOAD_PROGRESS_POSITIONS, OTP_INPUT_SIZES, PHONE_VERIFY_SIZES, EMAIL_VERIFY_SIZES, TWO_FACTOR_SIZES, CHAT_ORB_SIZES, CHAT_ORB_VARIANTS, CHAT_ORB_STATES, CHAT_ORB_THEMES, CHAT_MESSAGE_ROLES, CHAT_WIDGET_VIEWS, CHAT_WIDGET_POSITIONS, ToastVariant, ToastPosition } from '@designbasekorea/ui-contracts';
+export { ToastPosition as DbToastPosition, ToastVariant as DbToastVariant } from '@designbasekorea/ui-contracts';
+
+/**
+ * 엘리먼트 id 생성.
+ *
+ * 각 컴포넌트가 `Math.random().toString(36)` 을 따로 굴리면 충돌 가능성이 있고,
+ * 무엇보다 SSR/스냅샷에서 diff 노이즈가 된다. 생성은 여기서만 한다.
+ *
+ * 규격: DX-UID
+ */
+/**
+ * `prefix` 로 시작하는 문서 내 고유 id 를 만든다.
+ *
+ * `crypto.randomUUID` 가 있으면 그 앞 8자리를 쓰고, 없으면 증가 카운터로 폴백한다.
+ * 어느 쪽이든 한 문서 안에서는 절대 겹치지 않는다.
+ */
+declare function dbUid(prefix?: string): string;
+/**
+ * 엘리먼트에 id 가 없으면 만들어 붙이고, 그 id 를 돌려준다.
+ *
+ * `aria-labelledby` / `aria-controls` 배선에 쓴다 — 소비자가 직접 지정한 id 는 존중한다.
+ */
+declare function ensureId(el: Element, prefix?: string): string;
+
+/**
+ * 정리(cleanup) 관리.
+ *
+ * `connectedCallback` 에서 등록한 리스너·타이머·observer 를 `disconnectedCallback`
+ * 에서 빠짐없이 해제하기 위한 도구. 등록과 해제를 한 줄로 묶어두면
+ * "add 는 했는데 remove 를 빠뜨리는" 실수가 구조적으로 불가능해진다.
+ *
+ * 규격: PERF-CLEANUP
+ */
+type Cleanup = () => void;
+/** 해제 함수를 모아뒀다가 한 번에 실행하는 가방 */
+declare class CleanupBag {
+    private items;
+    /** 해제 함수를 직접 등록 */
+    add(fn: Cleanup): void;
+    /** 리스너를 달고 해제 함수를 자동 등록 */
+    listen<T extends EventTarget>(target: T, type: string, handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    /** setTimeout — 해제 시 자동 clear */
+    timeout(fn: () => void, ms: number): number;
+    /** setInterval — 해제 시 자동 clear */
+    interval(fn: () => void, ms: number): number;
+    /** MutationObserver / ResizeObserver / IntersectionObserver 등록 */
+    observe<T extends {
+        disconnect(): void;
+    }>(observer: T): T;
+    /** 등록된 모든 해제 함수를 실행하고 비운다. 여러 번 호출해도 안전하다. */
+    run(): void;
+}
+/** 스크롤/리사이즈처럼 고빈도로 발생하는 핸들러를 프레임당 1회로 병합한다. (PERF-RAF) */
+declare function rafThrottle<A extends unknown[]>(fn: (...args: A) => void): ((...args: A) => void) & {
+    cancel(): void;
+};
+
+/**
+ * 포커스 트랩.
+ *
+ * 모달·드로어·바텀시트 같은 오버레이가 열려 있는 동안 Tab 이 오버레이 밖으로
+ * 새어나가지 않게 하고, 닫을 때 **열기 직전에 포커스를 갖고 있던 요소로 되돌린다**.
+ * 포커스 복원이 없으면 키보드 사용자는 모달을 닫는 순간 문서 맨 앞으로 튕긴다.
+ *
+ * 규격: A11Y-TRAP, A11Y-AUTOFOCUS
+ */
+/** 컨테이너 안에서 Tab 순서대로 포커스 가능한 요소들 */
+declare function getTabbables(container: HTMLElement): HTMLElement[];
+interface FocusTrapOptions {
+    /**
+     * 활성화 시 포커스를 받을 요소.
+     * 지정하지 않으면 `[autofocus]` → 첫 포커서블 → 컨테이너 순으로 결정한다.
+     */
+    initialFocus?: HTMLElement | (() => HTMLElement | null) | null;
+    /** 해제 시 포커스를 돌려줄 요소. 기본값은 활성화 직전의 `document.activeElement` */
+    returnFocus?: HTMLElement | null;
+    /** 포커스 복원을 끄고 싶을 때 (기본 true) */
+    restoreFocus?: boolean;
+}
+interface FocusTrap {
+    activate(): void;
+    deactivate(): void;
+    /** 컨테이너 내용이 바뀌었을 때 포커서블 목록을 다시 계산할 필요는 없다 — 매번 조회하므로 no-op 호환용 */
+    readonly active: boolean;
+}
+/**
+ * `container` 안에 포커스를 가두는 트랩을 만든다.
+ *
+ * ```ts
+ * this.trap = createFocusTrap(panel);
+ * this.trap.activate();   // 열 때
+ * this.trap.deactivate(); // 닫을 때 — 포커스가 트리거로 돌아간다
+ * ```
+ */
+declare function createFocusTrap(container: HTMLElement, options?: FocusTrapOptions): FocusTrap;
+
+/**
+ * 문서 스크롤 잠금.
+ *
+ * 각 오버레이가 `document.body.style.overflow` 를 직접 만지면, 모달 위에 드로어를
+ * 띄웠다가 드로어만 닫는 순간 스크롤락이 통째로 풀린다. 잠금은 참조 카운트로만 관리한다.
+ *
+ * 규격: PERF-GLOBAL-STATE
+ */
+/**
+ * 문서 스크롤을 잠근다. 중첩 호출은 카운트되며, 같은 횟수만큼 `unlockScroll()`
+ * 해야 실제로 풀린다.
+ */
+declare function lockScroll(): void;
+/** `lockScroll()` 을 되돌린다. 카운트가 0 이 될 때만 실제로 해제된다. */
+declare function unlockScroll(): void;
+/** 현재 잠금 카운트 — 테스트/디버깅용 */
+declare function scrollLockDepth(): number;
+
+/**
+ * 접근성 런타임 유틸.
+ *
+ * 규격: A11Y-LIVE, A11Y-NAME
+ */
+type Politeness = 'polite' | 'assertive';
+/**
+ * 스크린리더에 메시지를 알린다.
+ *
+ * @param message    읽어줄 문장
+ * @param politeness `polite` 는 현재 읽는 것을 끝낸 뒤, `assertive` 는 즉시 끼어든다.
+ *                   오류·경고에만 assertive 를 쓴다.
+ */
+declare function announce(message: string, politeness?: Politeness): void;
+/** 피드백 톤에 맞는 politeness. danger/warning 만 즉시 끼어든다. */
+declare function politenessForTone(tone: string): Politeness;
+/**
+ * 접근 가능한 이름을 붙인다.
+ *
+ * 보이는 텍스트가 이미 있으면 `aria-label` 로 덮어쓰지 않는다 — 스크린리더 사용자와
+ * 음성 제어 사용자가 서로 다른 이름을 보게 되는 문제를 막는다.
+ */
+declare function setAccessibleName(el: HTMLElement, name: string): void;
+/** 시각적으로만 감춘 텍스트 노드를 만든다 (스크린리더는 읽음) */
+declare function createSrOnly(text: string): HTMLSpanElement;
+/**
+ * 네이티브가 아닌 요소(`role="button"` 을 얹은 div 등)에 Enter/Space 활성화를 붙인다.
+ *
+ * 네이티브 `<button>` 은 브라우저가 이걸 해 주지만, 커스텀 엘리먼트 호스트에
+ * role 만 얹은 경우에는 직접 배선해야 마우스와 키보드가 같아진다.
+ *
+ * 규격: A11Y-KEYBOARD
+ *
+ * @returns 등록을 해제하는 함수
+ */
+declare function activateOnKey(el: HTMLElement, options?: {
+    isDisabled?: () => boolean;
+}): () => void;
+
+/**
+ * 사용자 노출 문자열.
+ *
+ * 컴포넌트 소스에 `'모달 닫기'` 같은 한국어를 박아두면 한국어 외 서비스에서는
+ * 스크린리더가 엉뚱한 언어를 읽는다. 문자열은 전부 여기를 통과시키고,
+ * 소비자가 `dbSetLocale()` 로 덮어쓸 수 있게 한다.
+ *
+ * 기본값은 현재 소스에 박혀 있던 한국어 그대로다 — 동작 변화 없이 교체 지점만 생긴다.
+ *
+ * 규격: DX-I18N
+ */
+/** 컴포넌트가 쓰는 문자열 키 → 기본(한국어) 값 */
+declare const DEFAULT_STRINGS: {
+    readonly close: "닫기";
+    readonly 'modal.close': "모달 닫기";
+    readonly 'drawer.close': "드로어 닫기";
+    readonly 'dialog.close': "대화상자 닫기";
+    readonly 'toast.close': "알림 닫기";
+    readonly clear: "지우기";
+    readonly clearAll: "모든 값 지우기";
+    readonly loading: "로딩 중";
+    readonly required: "필수";
+    readonly optional: "선택";
+    readonly error: "오류";
+    readonly success: "성공";
+    readonly warning: "경고";
+    readonly info: "안내";
+    readonly previous: "이전";
+    readonly next: "다음";
+    readonly 'select.placeholder': "선택하세요";
+    readonly 'select.noResults': "결과 없음";
+    readonly 'tabs.label': "탭 목록";
+    readonly 'pagination.label': "페이지 번호";
+    readonly 'search.label': "검색";
+    readonly 'media.play': "재생";
+    readonly 'media.pause': "일시정지";
+    readonly 'media.mute': "음소거";
+    readonly 'media.unmute': "음소거 해제";
+    readonly 'media.settings': "설정";
+    readonly 'media.shuffle': "셔플";
+    readonly 'media.repeat': "반복";
+    readonly 'media.previous': "이전 트랙";
+    readonly 'media.next': "다음 트랙";
+    readonly 'media.fullscreen': "전체화면";
+    readonly 'carousel.previous': "이전 슬라이드";
+    readonly 'carousel.next': "다음 슬라이드";
+    readonly 'breadcrumbs.expand': "생략된 경로 펼치기";
+    readonly 'input.showPassword': "비밀번호 보기";
+    readonly 'input.hidePassword': "비밀번호 숨기기";
+    readonly 'input.clearSearch': "검색어 지우기";
+    readonly 'verify.done': "인증 완료";
+    readonly 'verify.phoneDone': "휴대폰 번호 인증이 완료되었습니다.";
+};
+type DbStringKey = keyof typeof DEFAULT_STRINGS;
+type DbStrings = Partial<Record<DbStringKey, string>> & Record<string, string>;
+/**
+ * 문자열을 전역으로 덮어쓴다. 앱 부트스트랩에서 한 번 호출한다.
+ *
+ * ```ts
+ * dbSetLocale({ 'modal.close': 'Close dialog', close: 'Close' });
+ * ```
+ */
+declare function dbSetLocale(strings: DbStrings): void;
+/** 현재 적용된 오버라이드를 모두 지운다 (테스트용) */
+declare function dbResetLocale(): void;
+/**
+ * 문자열을 조회한다.
+ *
+ * @param key      문자열 키
+ * @param fallback 키가 사전에 없을 때 쓸 값
+ */
+declare function t(key: DbStringKey | string, fallback?: string): string;
+/**
+ * 엘리먼트에서 라벨을 읽는다 — 소비자가 준 속성이 항상 우선한다.
+ *
+ * 컴포넌트는 `label-close` 같은 속성으로 개별 오버라이드를 받고,
+ * 없으면 전역 로케일로 폴백한다.
+ */
+declare function labelFrom(el: Element, attribute: string, key: DbStringKey | string): string;
+
+/**
+ * 선택적 베이스 클래스.
+ *
+ * 기존 130개 컴포넌트는 전부 `extends HTMLElement` 이며 그대로 동작한다.
+ * 새 컴포넌트나 개선 대상만 이 클래스를 상속하면 정리(cleanup)와 이벤트 발행이
+ * 규격에 맞게 강제된다. **상속은 강제가 아니다.**
+ *
+ * 규격: PERF-CLEANUP, STD-EVENT
+ */
+
+declare abstract class DbElement extends HTMLElement {
+    /**
+     * `connectedCallback` 에서 등록한 것들을 담아두는 가방.
+     * `disconnectedCallback` 에서 자동으로 비워진다.
+     */
+    protected readonly cleanups: CleanupBag;
+    /**
+     * 하위 클래스는 `disconnectedCallback` 을 오버라이드할 때 반드시
+     * `super.disconnectedCallback()` 을 호출해야 한다.
+     */
+    disconnectedCallback(): void;
+    /**
+     * 규격에 맞는 커스텀 이벤트를 발행한다 — `db-` 접두사 + bubbles + composed.
+     *
+     * @returns `preventDefault()` 되지 않았으면 true
+     */
+    protected dbEmit<T>(name: string, detail?: T, options?: {
+        cancelable?: boolean;
+    }): boolean;
+    /**
+     * 커스텀 엘리먼트가 정의되기 **전에** 프레임워크가 프로퍼티로 값을 넣어둔 경우,
+     * 그 값은 인스턴스 자체 프로퍼티로 남아 접근자를 가린다. 정의 후 회수한다.
+     *
+     * 규격: STD-UPGRADE
+     */
+    protected upgradeProperties(names: string[]): void;
+}
+
 /**
  * Light DOM custom element for the canonical web Button.
  *
@@ -6,10 +278,15 @@
  */
 declare class DbButton extends HTMLElement {
     static get observedAttributes(): string[];
+    /**
+     * 계약에 없는 값이 attribute 로 들어오면 기본값으로 되돌린다 — throw 하지 않는다.
+     * 커스텀 엘리먼트의 attribute 는 임의 문자열을 받으므로 타입으로 막을 수 없다. (STD-COERCE)
+     */
     get variant(): string;
     set variant(value: string);
     get size(): string;
     set size(value: string);
+    /** 빈 값은 "사이즈에 따라 자동" 을 뜻하므로 계약값에 포함되지 않아도 유효하다 */
     get radius(): string;
     set radius(value: string);
     get accentStyle(): string;
@@ -42,6 +319,14 @@ declare class DbButton extends HTMLElement {
     private getDefaultRadiusClass;
     private syncRadius;
     private syncAccentStyle;
+    /**
+     * outline 스타일의 회전하는 테두리 글로우.
+     *
+     * conic-gradient 의 각도를 직접 애니메이션하려면 `@property` 가 필요해 기준선이 올라간다.
+     * 대신 넘치는 정사각형을 `overflow: hidden` 컨테이너 안에서 회전시키고,
+     * 컨테이너의 `::after` 가 안쪽을 덮어 1.5px 테두리만 남기는 방식을 쓴다.
+     */
+    private syncAccentRing;
     private syncAccentField;
     private syncModifier;
     private syncBooleanModifier;
@@ -55,6 +340,8 @@ declare global {
 }
 
 declare class DbInput extends HTMLElement {
+    /** 현재 렌더된 DOM 구조의 형태 키 — 바뀔 때만 재구축한다 (PERF-RECONCILE) */
+    private shapeKey;
     static get observedAttributes(): string[];
     private input?;
     private passwordVisible;
@@ -84,6 +371,11 @@ declare class DbInput extends HTMLElement {
     private resolveIconName;
     private resolveStartIcon;
     private getCurrentValue;
+    /**
+     * DOM 골격을 만든다. 구조가 실제로 달라질 때만 호출되며,
+     * 그 외에는 render() 가 기존 노드의 속성만 갱신한다.
+     */
+    private buildStructure;
     private render;
     private mountIcons;
     private shouldShowPasswordValidation;
@@ -111,6 +403,8 @@ declare class DbCheckbox extends HTMLElement {
     private visual?;
     private labelEl?;
     private built;
+    private userInteracted;
+    private readonly cleanups;
     get checked(): boolean;
     set checked(value: boolean);
     get indeterminate(): boolean;
@@ -121,13 +415,22 @@ declare class DbCheckbox extends HTMLElement {
     set readOnly(value: boolean);
     get required(): boolean;
     set required(value: boolean);
+    /** 계약에 없는 값은 기본값으로 되돌린다 — throw 하지 않는다 (STD-COERCE) */
     get size(): string;
     set size(value: string);
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** form.reset() 이후 네이티브 input 의 실제 상태를 호스트 attribute 로 되돌린다 */
+    private syncAfterReset;
     attributeChangedCallback(name: string): void;
     private get hasLabel();
     private build;
     private handleChange;
+    /**
+     * 네이티브 검증 상태를 보조기술에 노출한다.
+     * 값 자체는 네이티브 input 이 폼에 싣고, 여기서는 표현만 맞춘다.
+     */
+    private syncValidity;
     private syncState;
     private syncVisual;
     private syncClasses;
@@ -145,6 +448,8 @@ declare class DbToggle extends HTMLElement {
     private root?;
     private labelEl?;
     private built;
+    /** default-checked 는 초기값일 뿐 — 한 번 조작하면 checked/selected 만 본다 */
+    private userInteracted;
     get checked(): boolean;
     set checked(value: boolean);
     get name(): string;
@@ -178,8 +483,8 @@ declare class DbBadge extends HTMLElement {
     set variant(value: string);
     get size(): string;
     set size(value: string);
-    get badgeStyle(): string;
-    set badgeStyle(value: string);
+    get type(): string;
+    set type(value: string);
     get count(): number | undefined;
     set count(value: number | undefined);
     get maxCount(): number;
@@ -230,6 +535,10 @@ declare global {
 }
 
 declare class DbSpinner extends HTMLElement {
+    /** 현재 그려진 스피너 타입 — 바뀔 때만 그래픽을 다시 만든다 */
+    private renderedType?;
+    private graphicEl?;
+    private labelEl?;
     static get observedAttributes(): string[];
     get type(): string;
     set type(value: string);
@@ -313,7 +622,7 @@ declare class DbTabs extends HTMLElement {
     private childObserver?;
     private resizeObserver?;
     private resizeRaf?;
-    get labels(): string[] | string;
+    get labels(): string[];
     set labels(value: string[] | string);
     get tabItems(): TabItemConfig[];
     get items(): TabItemConfig[];
@@ -359,6 +668,7 @@ declare class DbModal extends HTMLElement {
     private segmentEl?;
     private contentEl?;
     private titleId;
+    private focusTrap?;
     private isMounted;
     private internalTabId;
     private internalSegment;
@@ -398,7 +708,16 @@ declare class DbModal extends HTMLElement {
     private exitTimerId;
     private syncVisibility;
     private syncOpenState;
+    /** 열릴 때 포커스를 패널 안으로 가둔다. 닫으면 직전 포커스 요소로 복원된다. */
+    private activateFocusTrap;
     private teardown;
+    /** 소비자가 `role="alertdialog"` 를 지정하지 않으면 dialog */
+    private dialogRole;
+    /**
+     * 본문 설명을 대화상자에 연결한다.
+     * `describedby` 로 id 를 직접 주거나, 없으면 본문 컨테이너를 자동으로 가리킨다.
+     */
+    private syncDescribedBy;
     private close;
     private handleDocumentKeyDown;
 }
@@ -552,7 +871,7 @@ declare class DbAccordion extends HTMLElement {
     set items(value: AccordionItemConfig[] | string);
     get allowMultiple(): boolean;
     set allowMultiple(value: boolean);
-    get expandedItems(): string[] | string;
+    get expandedItems(): string[];
     set expandedItems(value: string[] | string);
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -678,6 +997,14 @@ declare class DbSelect extends HTMLElement {
     private getFilteredOptions;
     private selectOption;
     private dispatchChange;
+    /**
+     * combobox 트리거에 접근 가능한 이름을 붙인다.
+     *
+     * 트리거는 `<div role="combobox">` 라서 `<label for>` 로는 연결되지 않는다.
+     * 라벨이 있으면 `aria-labelledby`, 없으면 소비자가 준 `aria-label`,
+     * 그것도 없으면 placeholder 를 이름으로 쓴다. (A11Y-NAME)
+     */
+    private syncAccessibleName;
     private syncState;
     private syncOpenState;
     private syncTrigger;
@@ -730,6 +1057,7 @@ declare class DbRadio extends HTMLElement {
     private dot?;
     private labelEl?;
     private built;
+    private userInteracted;
     get checked(): boolean;
     set checked(value: boolean);
     get disabled(): boolean;
@@ -801,7 +1129,7 @@ declare class DbBreadcrumbs extends HTMLElement {
     private openMenuId;
     private onDocumentMouseDown;
     private onDocumentKeyDown;
-    get items(): BreadcrumbItem[] | string;
+    get items(): BreadcrumbItem[];
     set items(value: BreadcrumbItem[] | string);
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -956,6 +1284,8 @@ declare global {
 declare class DbBackdrop extends HTMLElement {
     static get observedAttributes(): string[];
     private portal?;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
     private keyHandler;
     get open(): boolean;
     set open(value: boolean);
@@ -969,6 +1299,8 @@ declare class DbBackdrop extends HTMLElement {
     private detachListeners;
     private handlePortalClick;
     private render;
+    /** 잠근 적이 있을 때만 푼다 — 참조 카운트가 음수로 새지 않도록 */
+    private releaseScrollLock;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -1042,15 +1374,19 @@ declare class DbDrawer extends HTMLElement {
     private root?;
     private overlay?;
     private container?;
+    private focusTrap?;
     private contentEl?;
     private isMounted;
     private isActive;
     private enterFrame?;
     private exitTimer?;
-    private previousActiveElement;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
     private keyHandler;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** 잠근 적이 있을 때만 푼다 — 카운트가 음수로 새지 않도록 */
+    private releaseScrollLock;
     attributeChangedCallback(name: string): void;
     private isOpenRequested;
     private clearTimers;
@@ -1074,14 +1410,21 @@ declare class DbToast extends HTMLElement {
     private progressInterval;
     private closeTimerId;
     private closed;
+    private readonly cleanups;
+    /** 일시정지 시점까지 소비한 시간 (ms) */
+    private elapsedBeforePause;
+    private runStartedAt;
+    private paused;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private pauseTimers;
+    private resumeTimers;
     attributeChangedCallback(name: string): void;
     private clearTimers;
     private startTimers;
     /** 토스트를 닫고(애니메이션 포함) auto-remove 설정 시 DOM에서 제거합니다. */
     close(): void;
-    private iconForStatus;
+    private iconForVariant;
     private render;
 }
 declare global {
@@ -1094,8 +1437,13 @@ declare class DbConfirm extends HTMLElement {
     static get observedAttributes(): string[];
     private root;
     private keyHandler;
+    private focusTrap?;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** 트랩 해제(=포커스 복원)와 스크롤락 반환을 한 곳에서 처리한다 */
+    private teardownOverlay;
     attributeChangedCallback(): void;
     private isOpen;
     private attachEscape;
@@ -1394,6 +1742,42 @@ declare global {
     }
 }
 
+type DbActivityHeatmapItem = {
+    date: string;
+    value: number;
+};
+type DbActivityHeatmapCellDetail = {
+    date: string;
+    value: number;
+    level: number;
+};
+declare class DbActivityHeatmap extends HTMLElement {
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private handleClick;
+    private parseData;
+    private parseEndDate;
+    private parseISODate;
+    private formatISODate;
+    private addDays;
+    private startOfWeek;
+    private isAfter;
+    private buildWeeks;
+    private resolveLevel;
+    private formatMonthLabel;
+    private formatTooltip;
+    private getDayLabels;
+    private getMonthLabels;
+    private render;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'db-activity-heatmap': DbActivityHeatmap;
+    }
+}
+
 declare class DbImage extends HTMLElement {
     private imageState;
     private currentSrc;
@@ -1485,6 +1869,10 @@ interface DbLightboxImage {
 }
 declare class DbLightbox extends HTMLElement {
     private portalEl;
+    private focusTrap?;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
+    private readonly titleId;
     private imageEl;
     private loadingEl;
     private errorEl;
@@ -1592,8 +1980,8 @@ interface DbNavbarUserProfile {
     email?: string;
     avatar?: string;
     badge?: number;
-    badgeVariant?: 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'danger';
-    badgeStyle?: 'dot' | 'number' | 'text' | 'outlined';
+    badgeVariant?: BadgeVariant;
+    badgeType?: BadgeType;
     badgeText?: string;
 }
 declare class DbNavbar extends HTMLElement {
@@ -1726,7 +2114,7 @@ interface DbSidebarItem {
     selected?: boolean;
     /** 프로필 메뉴에서 이 항목 앞에 구분선을 표시합니다. */
     dividerBefore?: boolean;
-    /** 클릭 시 이동할 사이드바 패널 id (예: settings) */
+    /** 클릭 시 이동할 사이드바 패널 id (예: authentication, settings) */
     openPanel?: string;
     children?: DbSidebarItem[];
 }
@@ -1737,6 +2125,20 @@ interface DbSidebarSection {
     gap?: 'none' | 's' | 'm' | 'l';
     items: DbSidebarItem[];
 }
+type DbSidebarPanelMode = 'auto' | 'adjacent' | 'replace';
+interface DbSidebarPanel {
+    id: string;
+    title: string;
+    description?: string;
+    ariaLabel?: string;
+    backLabel?: string;
+    /**
+     * @deprecated 레이아웃 폭은 전역 `panel-width`만 사용합니다.
+     * 패널마다 다른 폭을 주면 adjacent에서 폭이 흔들립니다.
+     */
+    width?: number | string;
+    sections: DbSidebarSection[];
+}
 interface DbSidebarUserProfile {
     name: string;
     email?: string;
@@ -1778,6 +2180,9 @@ declare class DbSidebar extends HTMLElement {
     private flyoutCloseTimer;
     private userFlyoutCloseTimer;
     private outsideHandler;
+    private panelMediaQuery;
+    private panelMediaHandler;
+    private resolvedPanelMode;
     /**
      * db-sidebar는 Light DOM으로 렌더링하므로 이름 있는 자식 요소를 직접 보존하고
      * 해당 내비게이션 영역으로 이동해 슬롯처럼 투영합니다.
@@ -1788,7 +2193,9 @@ declare class DbSidebar extends HTMLElement {
     static get observedAttributes(): string[];
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(name: string): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private bindPanelMediaQuery;
+    private unbindPanelMediaQuery;
     private seedExpanded;
     get items(): DbSidebarItem[];
     set items(value: DbSidebarItem[] | string);
@@ -1826,12 +2233,27 @@ declare class DbSidebar extends HTMLElement {
     set backLabel(value: string);
     get backHref(): string;
     set backHref(value: string);
+    get panels(): DbSidebarPanel[];
+    set panels(value: DbSidebarPanel[] | string);
+    /**
+     * @deprecated panels를 사용하세요. 기존 settings-sections는 settings 패널로 자동 변환됩니다.
+     */
     get settingsSections(): DbSidebarSection[];
     set settingsSections(value: DbSidebarSection[] | string);
     get activePanel(): string;
     set activePanel(value: string);
+    get panelMode(): DbSidebarPanelMode;
+    set panelMode(value: DbSidebarPanelMode);
+    get panelWidth(): string;
+    set panelWidth(value: string | number);
+    get panelBreakpoint(): number;
+    set panelBreakpoint(value: number);
+    private normalizeCssLength;
     private parseSettingsSections;
-    private hasSettingsPanel;
+    private parsePanels;
+    private hasPanels;
+    private findPanel;
+    private getActivePanelConfig;
     private parseSections;
     private parseUserMenuItems;
     private parseUserProfile;
@@ -1852,7 +2274,6 @@ declare class DbSidebar extends HTMLElement {
     private setUserFlyout;
     private scheduleUserFlyoutClose;
     private syncHostClasses;
-    private syncActivePanelTrack;
     private navigateToPanel;
     private dispatchItemClick;
     private dispatchUserMenuItemClick;
@@ -1873,8 +2294,10 @@ declare class DbSidebar extends HTMLElement {
     private createUserDropdown;
     private createUpdateBanner;
     private createPromoBanner;
-    private createHeader;
+    private createMainHeader;
+    private createPanelHeader;
     private createNavWrapper;
+    private createFooter;
     private render;
 }
 declare global {
@@ -1965,10 +2388,6 @@ declare global {
     }
 }
 
-/**
- * RangeSlider Web Component
- * packages/ui RangeSlider.tsx와 DOM·동작·스타일 1:1 동기화
- */
 declare class DbRangeSlider extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
@@ -2024,6 +2443,10 @@ declare class DbRangeSlider extends HTMLElement {
     private getTrackPercent;
     private handleThumbPointerDown;
     private handleTrackClick;
+    /**
+     * 포인터 이동을 프레임당 1회로 병합한다. preventDefault 를 쓰지 않으므로 안전하다. (PERF-RAF)
+     * 메서드가 아니라 필드로 선언해야 rafThrottle 로 감쌀 수 있다.
+     */
     private handlePointerMove;
     private handlePointerUp;
     private setThumbActive;
@@ -2034,6 +2457,11 @@ declare class DbRangeSlider extends HTMLElement {
     private dispatchValueChange;
     private dispatchRangeChange;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'db-range-slider': DbRangeSlider;
+    }
+}
 
 /**
  * SegmentControl Web Component
@@ -2355,6 +2783,7 @@ declare global {
 }
 
 declare class DbFloatingActionButton extends HTMLElement {
+    private detachKeyActivation?;
     static get observedAttributes(): string[];
     get size(): string;
     set size(value: string);
@@ -2385,6 +2814,9 @@ declare class DbBottomSheet extends HTMLElement {
     private grabBar?;
     private contentEl?;
     private sheetHeightPercent;
+    private focusTrap?;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
     private isDragging;
     private isVisible;
     private isMounted;
@@ -2398,6 +2830,8 @@ declare class DbBottomSheet extends HTMLElement {
     private shouldMountPortal;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** 트랩 해제(=포커스 복원)와 스크롤락 반환 */
+    private teardownOverlay;
     attributeChangedCallback(name: string): void;
     private isOpenRequested;
     private clearTimers;
@@ -2484,6 +2918,9 @@ type OnboardingStep = {
 declare class DbOnboardingModal extends HTMLElement {
     static get observedAttributes(): string[];
     private root?;
+    private focusTrap?;
+    /** 참조 카운트 스크롤락을 이 인스턴스가 잡고 있는지 (PERF-GLOBAL-STATE) */
+    private scrollLocked;
     private internalStep;
     private keyHandler;
     private isMounted;
@@ -2610,6 +3047,9 @@ declare class DbDatePicker extends HTMLElement {
     private boundDocumentMouseDown;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** 열린 달력은 Escape 로 닫히고 포커스는 트리거로 돌아간다 (A11Y-ESCAPE) */
+    private handleDocumentKeyDown;
+    private boundDocumentKeyDown;
     attributeChangedCallback(name: string): void;
     get value(): string;
     set value(value: string);
@@ -2646,7 +3086,7 @@ declare class DbDatePicker extends HTMLElement {
     private handlePendingApply;
     private handlePendingCancel;
     private handleInputBlur;
-    private get disabled();
+    get disabled(): boolean;
     set disabled(value: boolean);
     get readonly(): boolean;
     set readonly(value: boolean);
@@ -2669,8 +3109,7 @@ declare global {
     }
 }
 
-declare const FORMATS: readonly ["12h", "24h", "12h-with-seconds", "24h-with-seconds"];
-type TimeFormat = (typeof FORMATS)[number];
+type TimeFormat = (typeof TIME_PICKER_FORMATS)[number];
 declare class DbTimePicker extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
@@ -2691,6 +3130,9 @@ declare class DbTimePicker extends HTMLElement {
     private boundDocumentMouseDown;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** 열린 드롭다운은 Escape 로 닫히고 포커스는 트리거로 돌아간다 (A11Y-ESCAPE) */
+    private handleDocumentKeyDown;
+    private boundDocumentKeyDown;
     attributeChangedCallback(name: string): void;
     get value(): string;
     set value(value: string);
@@ -3317,8 +3759,17 @@ declare class DbResizablePanels extends HTMLElement {
     private startSize;
     private startPos;
     private currentSize;
+    /** 포인터 이동을 프레임당 1회로 병합하기 위한 핸들 (PERF-RAF) */
+    private rafId;
+    private pendingPoint;
     static get observedAttributes(): string[];
     connectedCallback(): void;
+    /**
+     * 드래그 중에 엘리먼트가 DOM 에서 제거되면 mouseup/touchend 가 오지 않아
+     * document 리스너가 영원히 남는다. 여기서 확실히 걷어낸다. (PERF-CLEANUP)
+     */
+    disconnectedCallback(): void;
+    private detachDragListeners;
     attributeChangedCallback(): void;
     private getBool;
     private getNumber;
@@ -3332,6 +3783,11 @@ declare class DbResizablePanels extends HTMLElement {
     private onTouchStart;
     private startResize;
     private onMouseMove;
+    /**
+     * pointer 이동마다 레이아웃을 다시 계산하면 프레임을 넘겨 버린다.
+     * 마지막 좌표만 남겨 두고 다음 프레임에 한 번만 반영한다.
+     */
+    private scheduleResize;
     private onTouchMove;
     private applyResize;
     private onMouseUp;
@@ -3384,6 +3840,9 @@ declare class DbVideoPlayer extends HTMLElement {
     private getPlaylist;
     private getCurrentSrc;
     private formatTime;
+    /**
+     * 아이콘만 있는 컨트롤 버튼. `label` 이 유일한 접근 가능한 이름이다. (A11Y-NAME)
+     */
     private iconButton;
     private skipButton;
     private syncFromAttributes;
@@ -3487,6 +3946,10 @@ declare class DbAudioPlayer extends HTMLElement {
     private toggleShuffle;
     private handlePlaybackRateChange;
     private handleKeyDown;
+    /**
+     * 아이콘만 있는 컨트롤 버튼. `label` 은 선택이 아니라 필수다 —
+     * 아이콘은 aria-hidden 이므로 이것이 유일한 접근 가능한 이름이 된다. (A11Y-NAME)
+     */
     private iconButton;
     private build;
     private get leftControls();
@@ -3703,6 +4166,7 @@ declare global {
 }
 
 declare class DbAppBadge extends HTMLElement {
+    private detachKeyActivation?;
     static get observedAttributes(): string[];
     private built;
     private labelEl?;
@@ -3713,6 +4177,7 @@ declare class DbAppBadge extends HTMLElement {
     private getStore;
     private getIconSize;
     private build;
+    disconnectedCallback(): void;
     private updateUI;
 }
 declare global {
@@ -4167,6 +4632,7 @@ type TutorialStep = {
 declare class DbTutorial extends HTMLElement {
     static get observedAttributes(): string[];
     private root?;
+    private focusTrap?;
     private overlayEl?;
     private popoverEl?;
     private closeButtonEl?;
@@ -4223,6 +4689,8 @@ declare class DbAnimationBackground extends HTMLElement {
     private syncingControls;
     static get observedAttributes(): string[];
     connectedCallback(): void;
+    /** 열린 설정 패널은 Escape 로 닫힌다 (A11Y-ESCAPE) */
+    private handleDocumentKeyDown;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private getBool;
@@ -4372,29 +4840,8 @@ declare global {
     }
 }
 
-declare class DbLottie extends HTMLElement {
-    private container?;
-    private animation?;
-    private loadToken;
-    static get observedAttributes(): string[];
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(): void;
-    private getBool;
-    private getSizeStyle;
-    private destroyAnimation;
-    private renderAnimation;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        'db-lottie': DbLottie;
-    }
-}
-
-declare const STATUSES: readonly ["downloading", "paused", "error", "complete"];
-type DownloadStatus = (typeof STATUSES)[number];
-declare const POSITIONS$1: readonly ["bottom-right", "bottom-left", "bottom-center", "top-right", "top-left", "top-center"];
-type DownloadPosition = (typeof POSITIONS$1)[number];
+type DownloadStatus = (typeof DOWNLOAD_PROGRESS_STATUSES)[number];
+type DownloadPosition = (typeof DOWNLOAD_PROGRESS_POSITIONS)[number];
 /**
  * 우측 하단(기본)에 떠 있는 다운로드 진행률 위젯.
  *
@@ -4481,8 +4928,7 @@ declare global {
  *
  * 분할 자릿수 OTP/PIN 입력. 붙여넣기·화살표·백스페이스를 지원합니다.
  */
-declare const SIZES$4: readonly ["s", "m", "l"];
-type OtpSize = (typeof SIZES$4)[number];
+type OtpSize = (typeof OTP_INPUT_SIZES)[number];
 declare class DbOtpInput extends HTMLElement {
     static formAssociated: boolean;
     static get observedAttributes(): string[];
@@ -4534,8 +4980,7 @@ declare global {
  * 한국형 휴대폰 본인인증: 통신사 → 번호 → 인증번호 발송 → OTP + 타이머/재전송.
  */
 
-declare const SIZES$3: readonly ["s", "m", "l"];
-type Size$2 = (typeof SIZES$3)[number];
+type Size$2 = (typeof PHONE_VERIFY_SIZES)[number];
 declare class DbPhoneVerify extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
@@ -4591,8 +5036,7 @@ declare global {
  * 이메일 인증: code(OTP) 모드 / confirm(메일함 확인) 모드.
  */
 
-declare const SIZES$2: readonly ["s", "m", "l"];
-type Size$1 = (typeof SIZES$2)[number];
+type Size$1 = (typeof EMAIL_VERIFY_SIZES)[number];
 declare class DbEmailVerify extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
@@ -4650,6 +5094,7 @@ declare global {
  * 2단계 인증(2FA): 인증앱 / SMS / 이메일 방식 + OTP.
  */
 
+type Size = (typeof TWO_FACTOR_SIZES)[number];
 declare const METHODS: readonly [{
     readonly value: "app";
     readonly label: "인증 앱";
@@ -4660,8 +5105,6 @@ declare const METHODS: readonly [{
     readonly value: "email";
     readonly label: "이메일";
 }];
-declare const SIZES$1: readonly ["s", "m", "l"];
-type Size = (typeof SIZES$1)[number];
 type Method = (typeof METHODS)[number]['value'];
 declare class DbTwoFactor extends HTMLElement {
     static get observedAttributes(): string[];
@@ -4709,14 +5152,10 @@ declare global {
     }
 }
 
-declare const SIZES: readonly ["xs", "s", "m", "l", "xl"];
-declare const VARIANTS: readonly ["aurora", "ocean", "emerald", "violet", "mono"];
-declare const STATES: readonly ["idle", "thinking", "listening"];
-declare const THEMES: readonly ["auto", "light", "dark"];
-type OrbSize = (typeof SIZES)[number];
-type OrbVariant = (typeof VARIANTS)[number];
-type OrbState = (typeof STATES)[number];
-type OrbTheme = (typeof THEMES)[number];
+type OrbSize = (typeof CHAT_ORB_SIZES)[number];
+type OrbVariant = (typeof CHAT_ORB_VARIANTS)[number];
+type OrbState = (typeof CHAT_ORB_STATES)[number];
+type OrbTheme = (typeof CHAT_ORB_THEMES)[number];
 /**
  * AI 어시스턴트를 상징하는 캔버스 기반 애니메이션 오브(구체).
  * 광택 있는 3D 구체 위에 유체처럼 흐르는 내부 광원 + 프레넬 림 라이트 + 스페큘러 하이라이트로
@@ -4909,6 +5348,8 @@ declare class DbChatComposer extends HTMLElement {
     private fileInput;
     private micBtn;
     private sendBtn;
+    private dropOverlay;
+    private dragDepth;
     get value(): string;
     set value(v: string);
     get streaming(): boolean;
@@ -4941,12 +5382,24 @@ declare class DbChatComposer extends HTMLElement {
     private handleOutsideClick;
     private chooseAttachOption;
     private handleFilePicked;
+    private hasDragFiles;
+    private handleDragEnter;
+    private handleDragOver;
+    private handleDragLeave;
+    private handleDrop;
+    private showDropOverlay;
     private addFile;
+    /** 동일 파일을 두 번 끌어놓거나 다시 선택해도 첨부 목록에는 한 번만 표시한다. */
+    private hasAttachment;
     private attachmentMeta;
     private handleInput;
     private handleKeyDown;
     private handleSendClick;
     private submit;
+    /** 여러 파일을 첨부합니다. */
+    addFiles(files: File[], type?: string): void;
+    /** 현재 입력·첨부를 전송합니다. */
+    send(): void;
     /** 입력 필드를 비웁니다. */
     clear(): void;
     /** 첨부를 하나 제거합니다. */
@@ -5005,8 +5458,14 @@ declare global {
     }
 }
 
-declare const ROLES: readonly ["user", "assistant", "system"];
-type Role = (typeof ROLES)[number];
+type Role = (typeof CHAT_MESSAGE_ROLES)[number];
+interface DbChatMessageAttachment {
+    name: string;
+    kind?: 'image' | 'video' | 'file';
+    /** 미리보기/다운로드 URL (blob: 또는 https:) */
+    url?: string;
+    mime?: string;
+}
 /**
  * 채팅 메시지 한 줄. 본문은 라이트 DOM 자식으로 전달하며 컴포넌트가 감쌉니다.
  * 아바타는 `db-avatar` 를 재사용합니다.
@@ -5020,17 +5479,22 @@ declare class DbChatMessage extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
     private contentEl;
+    private mediaEl;
     private avatarWrap;
     private headerEl;
     private nameEl;
     private timeEl;
     private actionsEl;
+    private _attachments;
     get role(): Role;
     set role(v: Role);
+    get attachments(): DbChatMessageAttachment[];
+    set attachments(list: DbChatMessageAttachment[]);
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
     private build;
     private sync;
+    private renderAttachments;
     private renderAvatar;
     private renderActions;
     private handleAction;
@@ -5060,10 +5524,10 @@ declare global {
     }
 }
 
-declare const VIEWS: readonly ["home", "messages", "conversation", "help"];
-type ChatView = (typeof VIEWS)[number];
-declare const POSITIONS: readonly ["bottom-right", "bottom-left"];
-type ChatPosition = (typeof POSITIONS)[number];
+type ChatView = (typeof CHAT_WIDGET_VIEWS)[number];
+type ChatPosition = (typeof CHAT_WIDGET_POSITIONS)[number];
+/** 홈 메뉴 선택 시 위젯 내부 이동. `none`이면 이벤트만 발행(호스트가 처리) */
+type DbChatWidgetMenuAction = 'conversation' | 'help' | 'none';
 interface DbChatWidgetMessage {
     id?: string;
     /** `assistant`(상담원/봇) 또는 `user` */
@@ -5075,6 +5539,13 @@ interface DbChatWidgetMessage {
     avatarInitials?: string;
     /** 말풍선 액션 (예: 'copy,like,dislike') — db-chat-message 로 전달 */
     actions?: string;
+    /** 첨부 파일/이미지 */
+    attachments?: Array<{
+        name: string;
+        kind?: 'image' | 'video' | 'file';
+        url?: string;
+        mime?: string;
+    }>;
 }
 interface DbChatWidgetConversation {
     id?: string;
@@ -5086,6 +5557,15 @@ interface DbChatWidgetConversation {
     unread?: number;
     online?: boolean;
 }
+/** 홈 바로가기 메뉴 — 필요한 항목만 `menuItems`로 전달 (없으면 숨김) */
+interface DbChatWidgetMenuItem extends DbChatSuggestion {
+    action?: DbChatWidgetMenuAction;
+}
+/** 도움말 문서 — 클릭 시 상세(`article`) 화면으로 이동 */
+interface DbChatWidgetArticle extends DbChatSuggestion {
+    /** 상세 본문. 없으면 description을 본문으로 사용 */
+    body?: string;
+}
 /**
  * FAB 로 열고 닫는 우측 하단 채팅 상담 위젯(껍데기).
  *
@@ -5099,11 +5579,12 @@ interface DbChatWidgetConversation {
  * @fires db-toggle      - FAB 토글 (detail: { open })
  * @fires db-view-change - 화면 전환 (detail: { view })
  * @fires db-send        - 메시지 전송 (detail: { text })
- * @fires db-menu-select - 홈 메뉴 선택 (detail: { id, value })
+ * @fires db-menu-select - 홈 메뉴 선택 (detail: { id, value, action })
  * @fires db-quick-reply - 빠른 답변 선택 (detail: { id, value })
  * @fires db-article-select      - 도움말 문서 선택 (detail: { id, title })
  * @fires db-conversation-select - 대화 목록 선택 (detail: { id })
  * @fires db-message-action      - 말풍선 액션 (detail: { action, text })
+ * @fires db-start-chat          - 대화 시작 CTA (홈·메시지 empty)
  *
  * @example
  *   const chat = document.createElement('db-chat-widget');
@@ -5122,6 +5603,8 @@ declare class DbChatWidget extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
     private typing;
+    private helpQuery;
+    private _activeArticle;
     private _messages;
     private _conversations;
     private _menuItems;
@@ -5148,16 +5631,24 @@ declare class DbChatWidget extends HTMLElement {
     get messages(): DbChatWidgetMessage[];
     set conversations(v: DbChatWidgetConversation[]);
     get conversations(): DbChatWidgetConversation[];
-    set menuItems(v: DbChatSuggestion[]);
-    get menuItems(): DbChatSuggestion[];
+    set menuItems(v: DbChatWidgetMenuItem[]);
+    get menuItems(): DbChatWidgetMenuItem[];
     set quickReplies(v: DbChatSuggestion[]);
     get quickReplies(): DbChatSuggestion[];
-    set articles(v: DbChatSuggestion[]);
-    get articles(): DbChatSuggestion[];
+    set articles(v: DbChatWidgetArticle[]);
+    get articles(): DbChatWidgetArticle[];
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** 열린 위젯 패널은 Escape 로 닫히고 포커스는 런처로 돌아간다 (A11Y-ESCAPE) */
+    private handleDocumentKeyDown;
     attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
     private hydrateFromAttributes;
     private build;
+    private panelDragDepth;
+    private handlePanelDragEnter;
+    private handlePanelDragOver;
+    private handlePanelDragLeave;
+    private handlePanelDrop;
     private sync;
     private syncOpenState;
     private renderBadge;
@@ -5168,9 +5659,14 @@ declare class DbChatWidget extends HTMLElement {
     private renderMessages;
     private renderConversation;
     private renderHelp;
+    private renderHelpResults;
+    private renderArticle;
+    private openArticle;
+    private startConversation;
     private buildMessage;
     private buildTyping;
     private buildEmpty;
+    private buildStartChatButton;
     private renderFooter;
     private renderNav;
     private scrollThreadToEnd;
@@ -5439,6 +5935,7 @@ interface DbChatRoomMessage {
     name?: string;
     avatarSrc?: string;
     avatarInitials?: string;
+    attachments?: DbChatMessageAttachment[];
 }
 /**
  * 사람 간 1:1/그룹 대화 화면. 상단 헤더(상대 정보) + 메시지 스레드 + 하단 컴포저.
@@ -5458,15 +5955,18 @@ declare class DbChatRoom extends HTMLElement {
     static get observedAttributes(): string[];
     private built;
     private typing;
+    private dragDepth;
     private _messages;
     private headerEl;
     private scrollEl;
     private threadEl;
     private dockEl;
+    private dropOverlay;
     private composer;
     set messages(v: DbChatRoomMessage[]);
     get messages(): DbChatRoomMessage[];
     connectedCallback(): void;
+    disconnectedCallback(): void;
     attributeChangedCallback(): void;
     private build;
     private sync;
@@ -5475,6 +5975,13 @@ declare class DbChatRoom extends HTMLElement {
     private buildMessage;
     private buildTyping;
     private scrollToEnd;
+    private nowLabel;
+    private hasDragFiles;
+    private handleDragEnter;
+    private handleDragOver;
+    private handleDragLeave;
+    private handleDrop;
+    private showDropOverlay;
     /** 메시지 추가. 추가된 id 반환 */
     addMessage(msg: DbChatRoomMessage): string;
     /** 전체 메시지 교체 */
@@ -5498,24 +6005,22 @@ declare global {
  * @example
  *   import { toast } from '@designbasekorea/ui-wc';
  *   toast.success('저장되었습니다');
- *   toast.error('오류가 발생했어요', { description: '잠시 후 다시 시도해 주세요' });
- *   const t = toast({ title: '업로드 중…', status: 'info', duration: 0 });
+ *   toast.danger('오류가 발생했어요', { description: '잠시 후 다시 시도해 주세요' });
+ *   const t = toast({ title: '업로드 중…', variant: 'info', duration: 0 });
  *   t.close();
  */
 
-type DbToastStatus = 'info' | 'success' | 'warning' | 'error';
-type DbToastPosition = 'top-right' | 'top-center' | 'top-left' | 'bottom-right' | 'bottom-center' | 'bottom-left';
 interface DbToastOptions {
     /** 제목 (필수) */
     title: string;
     /** 보조 설명 */
     description?: string;
     /** 상태 색상/아이콘. 기본 'info' */
-    status?: DbToastStatus;
+    variant?: ToastVariant;
     /** 자동 닫힘 시간(ms). 0 이하이면 자동으로 닫히지 않음. 기본 5000 */
     duration?: number;
     /** 표시 위치. 기본 'top-right' */
-    position?: DbToastPosition;
+    position?: ToastPosition;
     /** 닫기 버튼 표시. 기본 true */
     showClose?: boolean;
     /** 진행 바 표시. 기본 false */
@@ -5529,16 +6034,16 @@ interface DbToastHandle {
     /** 토스트를 수동으로 닫습니다(애니메이션 포함). */
     close: () => void;
 }
-type DbToastShortcut = (title: string, options?: Omit<DbToastOptions, 'title' | 'status'>) => DbToastHandle;
+type DbToastShortcut = (title: string, options?: Omit<DbToastOptions, 'title' | 'variant'>) => DbToastHandle;
 interface DbToastApi {
     (options: DbToastOptions): DbToastHandle;
     show: (options: DbToastOptions) => DbToastHandle;
     success: DbToastShortcut;
-    error: DbToastShortcut;
+    danger: DbToastShortcut;
     warning: DbToastShortcut;
     info: DbToastShortcut;
     /** 열려 있는 토스트를 모두 닫습니다. position 지정 시 해당 위치만. */
-    dismissAll: (position?: DbToastPosition) => void;
+    dismissAll: (position?: ToastPosition) => void;
 }
 /** 토스트를 띄웁니다. `toast(options)` 와 동일합니다. */
 declare function showToast(options: DbToastOptions): DbToastHandle;
@@ -5572,5 +6077,5 @@ interface DbConfirmOptions {
 /** 확인 대화상자를 띄우고, 확인 시 true / 취소(ESC·배경 포함) 시 false 로 resolve 합니다. */
 declare function confirm(options: DbConfirmOptions): Promise<boolean>;
 
-export { DbAccordion, DbAdBanner, DbAiChat, DbAiChatList, DbAlert, DbAnimationBackground, DbAnimationText, DbAppBadge, DbAudioPlayer, DbAvatar, DbBackdrop, DbBadge, DbBanner, DbBottomNavigation, DbBottomSheet, DbBreadcrumbs, DbButton, DbCalendar, DbCard, DbCarousel, DbChatComposer, DbChatList, DbChatMessage, DbChatOrb, DbChatRoom, DbChatSuggestions, DbChatTyping, DbChatWelcome, DbChatWidget, DbCheckbox, DbChip, DbCodeBlock, DbColorPicker, DbColorSwatch, DbConfirm, DbContainer, DbContextMenu, DbCookieBanner, DbCountdown, DbCursorFollower, DbDatePicker, DbDivider, DbDownloadProgress, DbDrawer, DbDropdown, DbDropzone, DbEmailVerify, DbEmptyState, DbFileUploader, DbFloatingActionButton, DbFooter, DbForm, DbGantt, DbGradient, DbGrid, DbGridBackground, DbGridItem, DbImage, DbImageList, DbImagePlaceholder, DbIndicator, DbInput, DbKanban, DbLabel, DbLightbox, DbList, DbLogo, DbLottie, DbMarkdownEditor, DbMarquee, DbMasonry, DbMenuItem, DbModal, DbNavbar, DbOnboardingModal, DbOtpInput, DbPageHeader, DbPagination, DbPhoneVerify, DbPopover, DbProgress, DbProgressStep, DbProgressbar, DbRadio, DbRandomGradient, DbRangeSlider, DbRating, DbReorder, DbResizablePanels, DbScrollArea, DbSearchBar, DbSection, DbSectionAppDownload, DbSectionContact, DbSectionCta, DbSectionFaq, DbSectionFeature, DbSectionFeatureGrid, DbSectionHero, DbSectionLogoCloud, DbSectionPricing, DbSectionStats, DbSectionTestimonials, DbSegmentControl, DbSelect, DbShare, DbSidebar, DbSignature, DbSkeleton, DbSpinner, DbSplitView, DbStack, DbStat, DbStepper, DbTable, DbTabs, DbTestimonial, DbTextarea, DbTimePicker, DbTimeline, DbToast, DbToggle, DbToolbar, DbTooltip, DbTopBanner, DbTutorial, DbTwoFactor, DbVideoPlayer, DbYouTubePlayer, confirm, confirm as dbConfirm, toast as dbToast, showToast, toast };
-export type { CalendarEventData, CalendarEventType, DbAiChatItem, DbAlertAction, DbArtifactOptions, DbBannerAction, DbBottomNavigationItem, DbChatArtifactRef, DbChatAttachOption, DbChatListItem, DbChatMessageData, DbChatRoomMessage, DbChatSuggestion, DbChatTool, DbChatWidgetConversation, DbChatWidgetMessage, DbColorSwatchCustomType, DbColorSwatchItem, DbColorSwatchShape, DbColorSwatchSize, DbConfirmOptions, DbConfirmVariant, DbFooterCompanyInfo, DbFooterFamilySite, DbFooterLink, DbFooterLinkColumn, DbFooterSocialLink, DbFormFieldData, DbGanttAssignee, DbGanttGroup, DbGanttItem, DbGanttItemStatus, DbGanttRow, DbImageListItem, DbKanbanAssignee, DbKanbanCard, DbKanbanColumn, DbKanbanPriority, DbKanbanTag, DbLightboxImage, DbNavbarItem, DbNavbarUserProfile, DbPageHeaderTabItem, DbSharePlatform, DbShareVariant, DbSidebarItem, DbSidebarProject, DbSidebarPromoBanner, DbSidebarSection, DbSidebarUserProfile, DbSignaturePoint, DbSignatureVariant, DbStatChange, DbTimelineItem, DbToastApi, DbToastHandle, DbToastOptions, DbToastPosition, DbToastStatus };
+export { CleanupBag, DbAccordion, DbActivityHeatmap, DbAdBanner, DbAiChat, DbAiChatList, DbAlert, DbAnimationBackground, DbAnimationText, DbAppBadge, DbAudioPlayer, DbAvatar, DbBackdrop, DbBadge, DbBanner, DbBottomNavigation, DbBottomSheet, DbBreadcrumbs, DbButton, DbCalendar, DbCard, DbCarousel, DbChatComposer, DbChatList, DbChatMessage, DbChatOrb, DbChatRoom, DbChatSuggestions, DbChatTyping, DbChatWelcome, DbChatWidget, DbCheckbox, DbChip, DbCodeBlock, DbColorPicker, DbColorSwatch, DbConfirm, DbContainer, DbContextMenu, DbCookieBanner, DbCountdown, DbCursorFollower, DbDatePicker, DbDivider, DbDownloadProgress, DbDrawer, DbDropdown, DbDropzone, DbElement, DbEmailVerify, DbEmptyState, DbFileUploader, DbFloatingActionButton, DbFooter, DbForm, DbGantt, DbGradient, DbGrid, DbGridBackground, DbGridItem, DbImage, DbImageList, DbImagePlaceholder, DbIndicator, DbInput, DbKanban, DbLabel, DbLightbox, DbList, DbLogo, DbMarkdownEditor, DbMarquee, DbMasonry, DbMenuItem, DbModal, DbNavbar, DbOnboardingModal, DbOtpInput, DbPageHeader, DbPagination, DbPhoneVerify, DbPopover, DbProgress, DbProgressStep, DbProgressbar, DbRadio, DbRandomGradient, DbRangeSlider, DbRating, DbReorder, DbResizablePanels, DbScrollArea, DbSearchBar, DbSection, DbSectionAppDownload, DbSectionContact, DbSectionCta, DbSectionFaq, DbSectionFeature, DbSectionFeatureGrid, DbSectionHero, DbSectionLogoCloud, DbSectionPricing, DbSectionStats, DbSectionTestimonials, DbSegmentControl, DbSelect, DbShare, DbSidebar, DbSignature, DbSkeleton, DbSpinner, DbSplitView, DbStack, DbStat, DbStepper, DbTable, DbTabs, DbTestimonial, DbTextarea, DbTimePicker, DbTimeline, DbToast, DbToggle, DbToolbar, DbTooltip, DbTopBanner, DbTutorial, DbTwoFactor, DbVideoPlayer, DbYouTubePlayer, activateOnKey, announce, confirm, createFocusTrap, createSrOnly, confirm as dbConfirm, dbResetLocale, dbSetLocale, toast as dbToast, dbUid, ensureId, getTabbables, labelFrom, lockScroll, politenessForTone, rafThrottle, scrollLockDepth, setAccessibleName, showToast, t, toast, unlockScroll };
+export type { CalendarEventData, CalendarEventType, Cleanup, DbActivityHeatmapCellDetail, DbActivityHeatmapItem, DbAiChatItem, DbAlertAction, DbArtifactOptions, DbBannerAction, DbBottomNavigationItem, DbChatArtifactRef, DbChatAttachOption, DbChatListItem, DbChatMessageAttachment, DbChatMessageData, DbChatRoomMessage, DbChatSuggestion, DbChatTool, DbChatWidgetArticle, DbChatWidgetConversation, DbChatWidgetMenuAction, DbChatWidgetMenuItem, DbChatWidgetMessage, DbColorSwatchCustomType, DbColorSwatchItem, DbColorSwatchShape, DbColorSwatchSize, DbConfirmOptions, DbConfirmVariant, DbFooterCompanyInfo, DbFooterFamilySite, DbFooterLink, DbFooterLinkColumn, DbFooterSocialLink, DbFormFieldData, DbGanttAssignee, DbGanttGroup, DbGanttItem, DbGanttItemStatus, DbGanttRow, DbImageListItem, DbKanbanAssignee, DbKanbanCard, DbKanbanColumn, DbKanbanPriority, DbKanbanTag, DbLightboxImage, DbNavbarItem, DbNavbarUserProfile, DbPageHeaderTabItem, DbSharePlatform, DbShareVariant, DbSidebarItem, DbSidebarProject, DbSidebarPromoBanner, DbSidebarSection, DbSidebarUserProfile, DbSignaturePoint, DbSignatureVariant, DbStatChange, DbStringKey, DbStrings, DbTimelineItem, DbToastApi, DbToastHandle, DbToastOptions, FocusTrap, FocusTrapOptions };