@iyulab/components 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # Changelog
 
+## [1.23.0] - 2026-08-04
+
+### Added
+
+- **`u-expander` — 제목을 눌러 본문을 접고 펴는 디스클로저.**
+
+  ```html
+  <u-expander label="배송 정보" open>
+    <p>본문</p>
+  </u-expander>
+  ```
+
+  헤더는 **네이티브 `<button>`** 이라 Enter/Space·포커스 순서가 그대로 따라온다. 높이 전환은
+  grid 트랙(`0fr` ↔ `1fr`)이라 콘텐츠 높이를 JS 로 재지 않으며, `prefers-reduced-motion:
+  reduce` 에서 멈춘다(접힘/펼침의 결과는 정지 상태에서도 그대로 읽히므로 이 전환은 장식이다).
+
+  ⚠**접힘의 요점은 높이가 아니라 «도달 불가»다** — `overflow: hidden` 만으로 접으면 화면에서
+  사라진 콘텐츠가 **접근성 트리와 탭 순서에 그대로 남는다.** `visibility` 를 함께 옮겨
+  접힌 본문이 포커스를 받지 못하게 한다(회귀 테스트가 이 조건만 따로 잰다).
+
+### Changed
+
+- **콘솔 진단 문구가 영어로 이주했다** — 토큰 시트 부재 경고 · `[Dialog]` 표시 실패 ·
+  `[IconRegistry]` 리졸브 실패. 화면 문자열이 아니라 **개발자 대면 진단**이고, 검색 가능성과
+  이슈 재현 공유에서 영어가 유리하다는 판단이다(로케일 레지스트리에 넣지 않는다 — 사용자가
+  읽는 문자열이 아니다). 문구를 판별식으로 쓰던 테스트가 있다면 *"무엇을 말하는가"* 로 좁힐 것.
+
+### Removed
+
+- 🔴**한 번도 동작한 적 없는 선언 3종을 걷었다.** 전부 «선언 + 문서»만 있고 그 값을 읽는
+  코드가 **어디에도 없었다**(전수 검색). 동작이 없었으므로 **깨질 동작도 없다.**
+
+  | 제거 | 문서가 약속하던 것 | 대체 |
+  |---|---|---|
+  | `u-panel[collapsible]` | *"Allow the panel to collapse"* | **`u-expander`**(위) |
+  | `u-tab-panel[editable]` | *"Allow adding/removing tabs"* | 없음 — 탭 추가/삭제는 소비자가 슬롯을 직접 다룬다 |
+  | `u-tree[droppable]` · `u-tree-item[droppable]` | *"Enable drop" / "Accepts drops"* | 없음 — 아래 참조 |
+
+  ⚠**`draggable` 은 남는다** — 그것은 네이티브 전역 속성이라 브라우저가 드래그 자체는
+  켜 준다. 다만 문서가 *"Allow reordering tabs by drag"*·*"Enable drag"* 로 **재정렬/드롭
+  기능을 약속**하고 있었고 그런 코드는 존재한 적이 없다 ⇒ **문서를 사실로 정정**했다
+  (*"native drag attribute — no built-in reordering"*). 드래그 재정렬·트리 드롭은 수요가
+  모이면 기능으로 설계한다.
+
+- **`Locale.namespace()` — 상위 패키지가 자기 화면 문자열을 담을 자리.**
+
+  ```ts
+  const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+  t.register('en', { empty: 'No data', loading: 'Loading…' });
+  t.register('ko', { empty: '데이터가 없습니다' });
+  t.text('empty');                     // 활성 로케일 기준
+  ```
+
+  종전의 `Locale.register`/`getValue` 는 **검증 메시지 9키의 닫힌 유니온**(`LocaleMessageKey`)만
+  받는다. 상위 패키지의 화면 문자열은 그 유니온에 없고, 넣으면 기반 라이브러리에 소비자
+  도메인 어휘가 쌓인다. ⇒ 결과적으로 각 패키지가 **자기 레지스트리를 손으로 만들거나**
+  문자열을 하드코딩해 왔다.
+
+  ⚠**순수 가산이다** — `LocaleMessageKey`·`register`·`getValue` 세 시그니처를 하나도
+  건드리지 않는다. 키 유니온은 **소비자가** 제네릭으로 정하므로 라이브러리 키셋은 커지지 않는다.
+
+  조회 사슬(정확 일치 → base 언어 → `en`)과 `{name}` 치환은 검증 메시지와 **같은 구현을
+  공유한다** — 두 벌로 두면 한쪽만 고쳐진다. 사슬에 없는 키는 **키 자체**를 돌려준다
+  (조용히 빈 문자열이 되는 것보다 화면에 드러나는 편이 낫다).
+
+- **`Theme.accent(seed)` — 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.**
+
+  ```ts
+  Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+  Theme.accent(null);        // 해제 — 시트 기본값으로
+  ```
+
+  종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+  아무것도 확인하지 않았다. 이제 **계산해서** 넣는다 — 면 위 글자 4.5 · 바탕 위 글자 4.5 ·
+  `-strong` ↔ `-color` 구분 1.20 · 그래픽 3.0.
+
+  ⚠**CSS `color-mix()` 만으로는 안 된다** — 고정 비율은 밝은 시드에서 깨진다(노랑의
+  `-strong` 이 바탕 대비 **2.21**, 기준 4.5). 목표 대비까지 섞으려면 대비를 **계산**해야
+  하고 CSS 에는 그 수단이 없다. ⇒ 계산은 JS, 결과만 커스텀 프로퍼티로.
+
+  ⚠**테마가 바뀌면 다시 계산된다** — 대비 목표가 «바탕 기준»이라 라이트와 다크는 같은
+  시드에서 **다른 램프**를 갖는다. 바탕은 계산 시점의 `--u-bg-color` 를 읽으므로 소비자가
+  바탕을 덮었으면 그 값이 기준이 된다.
+
+- **`u-skeleton` 에 `lines` — 여러 줄 자리표시자.**
+
+  ```html
+  <u-skeleton lines="3" height="1em"></u-skeleton>   <!-- 막대 3개 · 마지막 줄은 짧게 -->
+  ```
+
+  종전에는 목록 한 줄·문단 자리표시자를 만들 때 **폭만 다른 막대를 손으로 반복**해야 했다
+  (이 리포 안에서만 12사용처). 마지막 줄을 짧게 그리는 것은 장식이 아니라 **문단의 끝**을
+  나타내는 신호다(`--skeleton-last-line-width`, 기본 60%). 줄 간격은
+  `--skeleton-line-gap`(기본 `0.5em`).
+
+  ⚠**단일 막대의 모양은 바뀌지 않는다** — `lines` 가 없으면 종전과 완전히 같고, 회귀
+  테스트가 그 계약을 감시한다. `pulse`/`shimmer` 는 줄마다 적용되며 `prefers-reduced-motion`
+  에서 함께 멈춘다.
+
+- **오버레이가 열릴 때 `autofocus` 를 존중하고, 없으면 첫 입력으로 간다** (`u-dialog`·`u-drawer`).
+
+  ```html
+  <u-drawer closable>
+    <span slot="header">주문 편집</span>
+    <u-input label="수량" autofocus></u-input>   <!-- 여기로 간다 -->
+  </u-drawer>
+  ```
+
+  종전에는 `focus-trap` 의 기본값(**첫 tabbable 노드**)에 맡겨져 있었다. 그 결과 ⑴`autofocus`
+  가 **무시되고**(focus-trap 은 그 속성을 보지 않는다) ⑵**버튼이 마크업 앞에 있으면 버튼이
+  포커스를 가져갔다**(확인/취소가 먼저 오는 다이얼로그가 그 모양이다 — 실측: 입력이 아니라
+  첫 버튼). ⇒ 순서를 계약으로 고정한다: `[autofocus]` → 첫 입력 컨트롤 → 첫 tabbable.
+
+  ⚠**시각적 변화가 있을 수 있다** — 버튼이 앞에 오는 다이얼로그는 이제 **입력**에서 시작한다.
+  기존 동작을 원하면 그 버튼에 `autofocus` 를 준다.
+
+- **`u-tag`·`u-badge` 에 `icon` — 상태가 «색 없이도» 구분된다.**
+
+  ```html
+  <u-tag color="danger" icon>실패</u-tag>     <!-- ✕ 원형 아이콘 -->
+  <u-tag color="success" icon>완료</u-tag>    <!-- ✓ 원형 아이콘 -->
+  ```
+
+  대비 계약(1.20.0)은 각 상태색이 **자기 바탕에서 읽히는가**를 지키지만 *구별되는가* 는 지키지
+  않는다 — 색각 이상(남성 약 8%)이나 흑백 인쇄에서는 «성공»과 «실패»가 같은 회색 알약이 된다.
+  역할 색 충돌 검사가 **색 공간에서**(ΔE) 세운 구분을 이 축은 **모양 공간에서** 세운다.
+
+  ⚠**의미가 없는 색에는 그리지 않는다** — 장식 축(`blue`·`purple` …)은 *색 자체*를 뜻하고
+  `neutral`·`primary` 는 상태가 아니다. 없는 의미를 아이콘으로 지어내면 그 아이콘이 **잘못된
+  정보를 나른다**. `u-badge variant="dot"` 도 콘텐츠를 렌더하지 않으므로 대상이 아니다.
+
+  ⚠**렌더는 가산이다** — `icon` 을 주지 않으면 종전 그대로다. 아이콘은 **내장 번들**에서 오므로
+  네트워크를 타지 않는다(오프라인에서도 그려진다).
+
+  ⚠**다만 번들 크기는 가산이 아니다** — `u-tag`·`u-badge` 가 `u-icon` 을 import 하고, 내부
+  아이콘 번들은 **빌드 시점 eager glob** 이다. 그래서 `dist/components/tag/UTag.js` 만 deep
+  import 하던 소비자도 이제 `UIcon`(2.3 KB)과 내장 SVG 세트(**~9.8 KB**, 19종)를 함께 받는다.
+  전체 라이브러리를 쓰는 소비자에게는 변화가 없다(이미 포함돼 있다).
+
+- **`u-skeleton` 의 `pulse`/`shimmer` 가 `prefers-reduced-motion: reduce` 에서 멈춘다.**
+
+  ⚠**스피너는 그대로 돈다** — 갈림길은 *멈추냐 마냐*가 아니라 **어느 움직임이 의미를
+  나르는가**였다. 스피너의 회전은 **신호**라 죽이면 진행 여부를 알 수 없다(WCAG 2.2.2 는
+  로딩 표시처럼 움직임이 본질인 것을 예외로 둔다). 스켈레톤은 **기본값이 이미 정적**이고
+  정지한 블록이 «로딩 중»을 그대로 나르므로 `pulse`/`shimmer` 는 장식이다.
+
+  ⚠시트의 reduce 규칙(`--u-duration-*: 0ms`)은 **`animation` 을 쓰는 자리에 닿지 않는다** —
+  지속시간 축을 경유하지 않기 때문이다. 그래서 컴포넌트에서 명시적으로 멈춘다.
+
+### Changed
+
+- ⚠**`u-dialog`·`u-drawer` 제목이 2px 작아진다** — `18px` 리터럴 → `--u-text-subtitle-size`(16px).
+
+  종전에는 *다이얼로그 제목 18 · 얼럿 제목 16* 으로 **같은 위계가 두 값**이었다. 18px 는
+  타입 스케일 7단에 **없는 단**이라 리터럴로만 존재할 수 있었고, 그래서 소비자가 스케일을
+  조율해도 이 두 자리는 따라오지 않았다.
+
+  ⚠**단을 늘리지 않았다** — 18px 를 요구하는 타이포 자리는 전수 **둘뿐**이고(`u-copy-button`
+  의 18px 는 아이콘 크기다), 단일 수요로 축을 늘리는 것은 선제 확장이다. 같은 패키지의
+  `u-alert` 가 이미 `subtitle` 을 쓰고 있어 **선례를 따랐다**.
+
+  ⚠**헤더의 닫기 버튼은 `font-size: inherit` 이라 함께 2px 작아진다.**
+
+  `tests/build/type-scale.test.ts` 가 *"제목 위계를 가진 컴포넌트가 같은 단을 읽는가"* 를
+  대조한다 — 리터럴로 다시 갈라지면 발화한다.
+
+### Fixed
+
+- **역할 색의 «의미 충돌» 검사를 뒀다**(`tests/build/role-color-collision.test.ts`).
+  대비 검사는 각 역할색을 **자기 바탕에 대해** 재므로 *"저장(primary)과 삭제(danger)가
+  같은 색"* 인 상태도 **양쪽 다 통과한다** — 대비는 *읽히는가*를 묻지 *구별되는가*를 묻지
+  않는다. 이제 역할끼리의 거리를 CIELAB ΔE 로 잰다(임계 20).
+
+  ⚠**`primary` 와 `info` 는 기본값이 의도적으로 같으므로 면제**다(브랜딩은 `primary` 만
+  바꾼다). 면제쌍의 **근거가 시트 주석에 남아 있는지**도 함께 잰다 — 근거 없는 면제가
+  쌓이면 검사가 아무것도 지키지 않게 된다.
+
+  실측: 면제쌍을 뺀 최소 거리가 **38.7**(라이트 `-strong` 의 warning/danger)이라 정상적인
+  램프 조율에는 발화하지 않는다.
+
 ## [1.22.0] - 2026-08-03
 
 ### Added

package/README.md

@@ -104,6 +104,38 @@ Theme.set('system');
 
 자세한 내용은 [docs/theming.md](./docs/theming.md)를 참고하세요.
 
+## Localization
+
+라이브러리가 **스스로 생성하는 문자열**(검증 메시지)은 내장 로케일 14종을 갖고 있으며,
+활성 로케일 하나로 전부 따라옵니다.
+
+```ts
+import { Locale } from '@iyulab/components';
+
+Locale.set('ko');                                   // 활성 로케일
+Locale.register('nl', { valueMissing: '…' });       // 검증 메시지 override
+```
+
+### 네임스페이스 — 상위 패키지·앱의 문자열 (1.23.0~)
+
+검증 메시지 키셋은 **닫혀 있습니다**(9키). 그 위에 자기 문자열을 담으려면 네임스페이스를
+씁니다 — 키 유니온은 **쓰는 쪽이** 정하므로 라이브러리 키셋은 커지지 않습니다.
+
+```ts
+const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+
+t.register('en', { empty: 'No data', loading: 'Loading…' });   // 기본은 영어
+t.register('ko', { empty: '데이터가 없습니다' });               // 필요한 언어만 추가
+
+t.text('empty');                        // 활성 로케일 기준
+t.text('greet', { who: 'Ann' });        // {name} 치환
+```
+
+- 조회 사슬은 검증 메시지와 같습니다: **정확 일치 → base 언어(`ko-KR` → `ko`) → `en`**.
+- 같은 이름의 네임스페이스는 **같은 저장소**를 가리킵니다(모듈 어디서 만들어도 됩니다).
+- 사슬에 없는 키는 **키 자체**를 돌려줍니다 — 조용히 빈 문자열이 되지 않습니다.
+- `Locale.set()` 하나로 검증 메시지와 네임스페이스가 함께 전환됩니다.
+
 ## Documentation
 
 | 문서 | 내용 |

package/dist/components/UOverlayElement.d.ts

@@ -65,6 +65,24 @@ export declare abstract class UOverlayElement extends UElement {
     requestClose(source: string): void;
     /** 오버레이가 열릴 때 설정을 적용합니다. */
     private setup;
+    /**
+     * 열릴 때 포커스를 받을 요소를 정한다 — **입력을 먼저 본다.**
+     *
+     * 순서: `[autofocus]` → 첫 입력 컨트롤 → (없으면) focus-trap 기본값(첫 tabbable).
+     *
+     * 🔴**두 분기가 «각각» 무엇을 하는지 되돌려 재서 갈랐다** — 이 함수는 그 기록이다.
+     *
+     *   `[autofocus]`  → `u-drawer` 에서 갈린다. `focus-trap` 은 그 속성을 존중하지 않는다
+     *                    (v7 `getInitialFocusNode` 는 «첫 tabbable» 로 폴백한다).
+     *   첫 입력 우선   → `u-dialog` 에서 갈린다. 버튼이 DOM 순서상 앞이면 기본값은 **버튼**을
+     *                    잡는다(실측: 제거하면 `button#b1`, 복원하면 `input`).
+     *
+     * ⚠**`u-drawer` 만으로는 두 번째 분기를 판별할 수 없었다** — 슬롯 배치 때문에 기본값도
+     * 우연히 첫 입력에 떨어진다. *"되돌려도 통과한다"* 를 *"이 코드는 아무것도 안 한다"* 로
+     * 읽을 뻔했고, **판별하는 입력을 찾은 뒤에야** 갈렸다.
+     * (`tests/browser/overlay-initial-focus.browser.test.ts` 가 둘 다 감시한다.)
+     */
+    private resolveInitialFocus;
     /** 오버레이가 닫힐 때 설정을 해제합니다. */
     private cleanup;
     /** host 자체를 클릭한 경우(백드롭)만 닫기 요청 */

package/dist/components/UOverlayElement.js

@@ -102,12 +102,36 @@ var UOverlayElement = class extends UElement {
 				clickOutsideDeactivates: false,
 				allowOutsideClick: true,
 				fallbackFocus: this,
+				initialFocus: () => this.resolveInitialFocus(),
 				trapStack: OverlayManager.trapStack,
 				tabbableOptions: { getShadowRoot: true }
 			});
 			this.focusTrap.activate();
 		}
 	}
+	/**
+	* 열릴 때 포커스를 받을 요소를 정한다 — **입력을 먼저 본다.**
+	*
+	* 순서: `[autofocus]` → 첫 입력 컨트롤 → (없으면) focus-trap 기본값(첫 tabbable).
+	*
+	* 🔴**두 분기가 «각각» 무엇을 하는지 되돌려 재서 갈랐다** — 이 함수는 그 기록이다.
+	*
+	*   `[autofocus]`  → `u-drawer` 에서 갈린다. `focus-trap` 은 그 속성을 존중하지 않는다
+	*                    (v7 `getInitialFocusNode` 는 «첫 tabbable» 로 폴백한다).
+	*   첫 입력 우선   → `u-dialog` 에서 갈린다. 버튼이 DOM 순서상 앞이면 기본값은 **버튼**을
+	*                    잡는다(실측: 제거하면 `button#b1`, 복원하면 `input`).
+	*
+	* ⚠**`u-drawer` 만으로는 두 번째 분기를 판별할 수 없었다** — 슬롯 배치 때문에 기본값도
+	* 우연히 첫 입력에 떨어진다. *"되돌려도 통과한다"* 를 *"이 코드는 아무것도 안 한다"* 로
+	* 읽을 뻔했고, **판별하는 입력을 찾은 뒤에야** 갈렸다.
+	* (`tests/browser/overlay-initial-focus.browser.test.ts` 가 둘 다 감시한다.)
+	*/
+	resolveInitialFocus() {
+		const explicit = this.querySelector("[autofocus]");
+		if (explicit) return explicit;
+		const control = this.querySelector("input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider");
+		if (control) return control;
+	}
 	/** 오버레이가 닫힐 때 설정을 해제합니다. */
 	cleanup() {
 		this.focusTrap?.deactivate();

package/dist/components/badge/UBadge.d.ts

@@ -22,6 +22,11 @@ export declare class UBadge extends UElement {
     color: BadgeColor;
     /** 부모 요소 기준 배치 위치 (설정 시 position: absolute) */
     anchor?: BadgeAnchor;
+    /**
+     * 상태를 **색과 무관하게** 나르는 아이콘을 붙입니다(`info`·`success`·`warning`·`danger`).
+     * 의미가 없는 색(`neutral`·`primary`·장식 축)과 `variant="dot"` 에서는 그리지 않습니다.
+     */
+    icon: boolean;
     render(): import('lit-html').TemplateResult<1> | typeof nothing;
 }
 declare global {

package/dist/components/badge/UBadge.js

@@ -1,6 +1,8 @@
 import { UElement } from "../UElement.js";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
+import "../icon/UIcon.js";
+import { statusIcon } from "../../utilities/statusIcon.js";
 import { styles } from "./UBadge.styles.js";
 import { html, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
@@ -10,14 +12,17 @@ var UBadge = class UBadge extends UElement {
 		super(..._args);
 		this.variant = "pill";
 		this.color = "blue";
+		this.icon = false;
 	}
 	static {
 		this.styles = [super.styles, styles];
 	}
 	render() {
 		if (this.variant === "dot") return nothing;
+		const iconName = this.icon ? statusIcon(this.color) : void 0;
 		return html`
       <div class="base" part="base">
+        ${iconName ? html`<u-icon class="icon" part="icon" lib="internal" name=${iconName}></u-icon>` : nothing}
         <slot name="prefix"></slot>
         <slot></slot>
         <slot name="suffix"></slot>
@@ -37,6 +42,10 @@ __decorate([property({
 	type: String,
 	reflect: true
 }), __decorateMetadata("design:type", Object)], UBadge.prototype, "anchor", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UBadge.prototype, "icon", void 0);
 UBadge = __decorate([customElement("u-badge")], UBadge);
 //#endregion
 export { UBadge };

package/dist/components/badge/UBadge.styles.js

@@ -140,6 +140,12 @@ var styles = css`
     transform: translate(-50%, 50%);
   }
 
+  /* 상태 아이콘 — prefix 슬롯과 같은 간격을 쓴다. */
+  .icon {
+    flex-shrink: 0;
+    margin-right: 0.25em;
+  }
+
   /* === Slots === */
   ::slotted([slot="prefix"]) {
     margin-right: 0.25em;

package/dist/components/dialog/UDialog.styles.js

@@ -89,7 +89,7 @@ var styles = css`
     justify-content: space-between;
     gap: var(--u-space-sm, 8px);
     padding: var(--u-space-md, 12px) var(--u-space-lg, 16px);
-    font-size: 18px;
+    font-size: var(--u-text-subtitle-size, 16px);
     font-weight: 600;
     line-height: 1.3;
     border-bottom: 1px solid var(--u-border-color, #E0E0E0);

package/dist/components/drawer/UDrawer.styles.js

@@ -77,7 +77,7 @@ var styles = css`
     justify-content: space-between;
     gap: var(--u-space-sm, 8px);
     padding: var(--u-space-md, 12px) var(--u-space-lg, 16px);
-    font-size: 18px;
+    font-size: var(--u-text-subtitle-size, 16px);
     font-weight: 600;
     line-height: 1.3;
     border-bottom: 1px solid var(--u-border-color, #E0E0E0);

package/dist/components/expander/UExpander.d.ts

@@ -0,0 +1,38 @@
+import { UElement } from '../UElement.js';
+/**
+ * 제목을 눌러 본문을 접고 펴는 디스클로저(익스팬더) 컴포넌트입니다.
+ *
+ * @slot - 펼쳤을 때 보이는 본문
+ * @slot header - 제목 영역을 통째로 대체하는 콘텐츠 (`label` 보다 우선)
+ * @slot suffix - 제목 우측에 놓이는 콘텐츠 (상태 배지·보조 액션 등)
+ *
+ * @csspart header - 제목 버튼 영역
+ * @csspart icon - 펼침 표시 아이콘
+ * @csspart label - 제목 텍스트 영역
+ * @csspart content - 본문을 감싸는 영역
+ *
+ * @event expand - 펼쳐질 때 발생 (취소 가능)
+ * @event collapse - 접힐 때 발생 (취소 가능)
+ */
+export declare class UExpander extends UElement {
+    static styles: import('lit').CSSResultGroup[];
+    /** 펼침 여부 */
+    open: boolean;
+    /** 비활성화 여부 */
+    disabled: boolean;
+    /** 제목 텍스트 (`header` 슬롯이 있으면 그쪽이 이깁니다) */
+    label: string;
+    render(): import('lit-html').TemplateResult<1>;
+    /** 펼칩니다. `expand` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+    expand(): boolean;
+    /** 접습니다. `collapse` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+    collapse(): boolean;
+    /** 현재 상태의 반대로 바꿉니다. */
+    toggle(): boolean;
+    private handleClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-expander': UExpander;
+    }
+}

package/dist/components/expander/UExpander.js

@@ -0,0 +1,78 @@
+import { UElement } from "../UElement.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
+import "../icon/UIcon.js";
+import { styles } from "./UExpander.styles.js";
+import { html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+//#region src/components/expander/UExpander.ts
+var UExpander = class UExpander extends UElement {
+	constructor(..._args) {
+		super(..._args);
+		this.open = false;
+		this.disabled = false;
+		this.label = "";
+		this.handleClick = () => {
+			this.toggle();
+		};
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	render() {
+		return html`
+      <div class="frame">
+        <button class="header" part="header" type="button"
+          aria-expanded=${this.open ? "true" : "false"}
+          aria-controls="content"
+          ?disabled=${this.disabled}
+          @click=${this.handleClick}
+        >
+          <u-icon class="icon" part="icon" lib="internal" name="chevron-right"></u-icon>
+          <span class="label" part="label"><slot name="header">${this.label}</slot></span>
+          <slot name="suffix"></slot>
+        </button>
+
+        <div class="content" part="content" id="content" role="region">
+          <div class="inner">
+            <div class="body"><slot></slot></div>
+          </div>
+        </div>
+      </div>
+    `;
+	}
+	/** 펼칩니다. `expand` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+	expand() {
+		if (this.disabled || this.open) return false;
+		if (this.fire("expand")) {
+			this.open = true;
+			return true;
+		}
+		return false;
+	}
+	/** 접습니다. `collapse` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+	collapse() {
+		if (this.disabled || !this.open) return false;
+		if (this.fire("collapse")) {
+			this.open = false;
+			return true;
+		}
+		return false;
+	}
+	/** 현재 상태의 반대로 바꿉니다. */
+	toggle() {
+		return this.open ? this.collapse() : this.expand();
+	}
+};
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UExpander.prototype, "open", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UExpander.prototype, "disabled", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UExpander.prototype, "label", void 0);
+UExpander = __decorate([customElement("u-expander")], UExpander);
+//#endregion
+export { UExpander };

package/dist/components/expander/UExpander.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import('lit').CSSResult;

package/dist/components/expander/UExpander.styles.js

@@ -0,0 +1,95 @@
+import { css } from "lit";
+//#region src/components/expander/UExpander.styles.ts
+var styles = css`
+  :host {
+    display: block;
+  }
+  :host([disabled]) {
+    opacity: 0.5;
+  }
+
+  /* ⚠테두리·면은 :host 가 아니라 내부 래퍼가 그린다 — :host 에 두면 소비 앱의 CSS
+     리셋(* { border: 0 })이 «에러 없이» 지운다(Tailwind preflight 가 가장 흔한 경우다).
+     이 리포는 그 결함을 9개 컴포넌트에서 이미 걷어냈고 회귀 테스트가 목록을 0 으로 잠근다
+     — tests/build/host-layout-reset.test.ts */
+  .frame {
+    border: 1px solid var(--u-border-color, #E0E0E0);
+    border-radius: var(--u-radius-md, 4px);
+    background-color: var(--u-bg-color, #FFFFFF);
+  }
+
+  .header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    width: 100%;
+    box-sizing: border-box;
+    padding: var(--u-space-sm, 8px) var(--u-space-md, 12px);
+    border: none;
+    border-radius: inherit;
+    background: none;
+    color: var(--u-txt-color, #212121);
+    font: inherit;
+    font-size: var(--u-text-body-size, 14px);
+    font-weight: var(--u-text-subtitle-weight, 600);
+    text-align: start;
+    cursor: pointer;
+  }
+  .header:disabled {
+    cursor: default;
+  }
+  .header:focus-visible {
+    outline: 2px solid var(--u-primary-color-strong, #1565C0);
+    outline-offset: -2px;
+  }
+
+  .icon {
+    flex: none;
+    color: var(--u-txt-color-weak, #757575);
+    transition: transform var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1));
+  }
+  :host([open]) .icon {
+    transform: rotate(90deg);
+  }
+
+  .label {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  /* 높이 애니메이션은 grid 트랙(0fr ↔ 1fr)으로 한다 — 콘텐츠 높이를 JS 로 재지 않는다.
+     ⚠전환을 지원하지 않는 엔진에서는 «즉시» 열리고 닫힐 뿐 접힘 자체는 성립한다
+     (0fr 은 그 엔진에서도 유효한 트랙 크기다).
+     ★visibility 를 함께 옮기는 것이 요점이다 — overflow: hidden 만으로는 접힌 콘텐츠가
+     여전히 접근성 트리와 탭 순서에 남는다. */
+  .content {
+    display: grid;
+    grid-template-rows: 0fr;
+    visibility: hidden;
+    transition:
+      grid-template-rows var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1)),
+      visibility var(--u-duration-normal, 220ms);
+  }
+  :host([open]) .content {
+    grid-template-rows: 1fr;
+    visibility: visible;
+  }
+  .inner {
+    overflow: hidden;
+  }
+  .body {
+    padding: 0 var(--u-space-md, 12px) var(--u-space-md, 12px);
+  }
+
+  /* 이 전환은 «장식»이다 — 접힘/펼침의 결과는 정지 상태에서도 그대로 읽힌다.
+     ⚠시트의 reduce 규칙(지속시간 축 0)에 기대지 않고 여기서도 누른다: 소비자가 토큰
+     시트를 로드하지 않으면 use-site 폴백 리터럴이 살아남아 그 규칙이 닿지 못한다. */
+  @media (prefers-reduced-motion: reduce) {
+    .icon,
+    .content {
+      transition-duration: 0s;
+    }
+  }
+`;
+//#endregion
+export { styles };

package/dist/components/panel/UPanel.d.ts

@@ -9,8 +9,6 @@ export declare class UPanel extends UElement {
     static styles: import('lit').CSSResultGroup[];
     /** 패널 비활성화 여부 */
     disabled: boolean;
-    /** 패널 접기 가능 여부 */
-    collapsible: boolean;
     /** 패널 고유값 (매칭 시 사용) */
     value: string;
     render(): import('lit-html').TemplateResult<1>;

package/dist/components/panel/UPanel.js

@@ -9,7 +9,6 @@ var UPanel = class UPanel extends UElement {
 	constructor(..._args) {
 		super(..._args);
 		this.disabled = false;
-		this.collapsible = false;
 		this.value = "";
 	}
 	static {
@@ -23,10 +22,6 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Object)], UPanel.prototype, "disabled", void 0);
-__decorate([property({
-	type: Boolean,
-	reflect: true
-}), __decorateMetadata("design:type", Object)], UPanel.prototype, "collapsible", void 0);
 __decorate([property({
 	type: String,
 	reflect: true

package/dist/components/skeleton/USkeleton.d.ts

@@ -22,6 +22,13 @@ export declare class USkeleton extends UElement {
     width?: string;
     /** 높이 (CSS 값) */
     height?: string;
+    /**
+     * 여러 줄 자리표시자로 그릴 줄 수. **2 이상일 때만** 호스트가 «막대들의 통»이 되고,
+     * 마지막 줄은 짧게(`--skeleton-last-line-width`, 기본 60%) 그린다 — 문단의 끝을 그렇게 읽는다.
+     *
+     * ⚠**단일 막대(기본)의 모양은 바꾸지 않는다** — 이 속성이 없으면 종전과 완전히 같다.
+     */
+    lines?: number;
     protected updated(changedProperties: PropertyValues): void;
     render(): import('lit-html').TemplateResult<1>;
 }

package/dist/components/skeleton/USkeleton.js

@@ -20,7 +20,9 @@ var USkeleton = class USkeleton extends UElement {
 		if (changedProperties.has("height") && this.height) this.style.setProperty("--skeleton-height", this.height);
 	}
 	render() {
-		return html`<slot></slot>`;
+		const n = this.lines ?? 0;
+		if (n < 2) return html`<slot></slot>`;
+		return html`${Array.from({ length: n }, () => html`<span class="line" part="line"></span>`)}`;
 	}
 };
 __decorate([property({
@@ -33,6 +35,10 @@ __decorate([property({
 }), __decorateMetadata("design:type", Object)], USkeleton.prototype, "effect", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], USkeleton.prototype, "width", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], USkeleton.prototype, "height", void 0);
+__decorate([property({
+	type: Number,
+	reflect: true
+}), __decorateMetadata("design:type", Number)], USkeleton.prototype, "lines", void 0);
 USkeleton = __decorate([customElement("u-skeleton")], USkeleton);
 //#endregion
 export { USkeleton };