@designbasekorea/ui-wc 0.8.13 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 변경 이력
 
+## 0.9.0 - 2026-10-22
+
+컴포넌트 패키지 `@designbasekorea/ui-wc` 단독 릴리스입니다. `@designbasekorea/blocks`, 페이지 템플릿과 갤러리 서비스는 이 npm 배포에 포함하지 않습니다.
+
+### 주요 추가 및 수정
+
+- 배포 타입: 전체·개별 컴포넌트·React 경로가 같은 선언을 참조하도록 정리하고, 새 공유 계약 타입을 패키지에 포함해 소비 프로젝트의 중복 전역 선언과 누락된 타입 오류를 수정.
+
+- Node: WC/React 노드 표면, 입력·출력 포트, 드래그/키보드 이동·연결 이벤트, 접기·개요 보기, 선택·삭제 요청과 상태 배지. 포인터 캡처가 끊겨도 마지막 위치를 유지하고 Esc만 이동을 취소합니다. 전체 그래프 편집기 예제의 저장·실행 로직은 호스트 앱이 담당합니다.
+- DesignCanvas, DesignToolbar, ContextBar, ToolButton: 디자인 편집 화면을 구성하는 공통 컴포넌트와 React 래퍼.
+- 디바이스 목업, FlightStatus·BoardingPassStack, 음성 입력, 달성 목록·모달 등 신규 컴포넌트.
+- 알림 목록·드롭다운, 작업 공간 멤버·초대, 첨부 파일 목록, 플랜·크레딧 이력과 실행 견적 컴포넌트.
+- BentoGrid·BentoCard, TweetCard, ProgressiveBlur, BorderBeam, Confetti, GlyphMatrix와 React 래퍼.
+- Button·Modal·Drawer·Sidebar·MenuItem·Navbar·Select·Textarea 등 기존 컴포넌트의 상호작용, 접근성, 토큰과 스타일 수정.
+- WC 전체 진입점, React 래퍼와 개별 컴포넌트 import를 제공합니다. 토큰·테마는 기존 설치 방식으로 별도 로드합니다.
+
+### 추가
+
+- CreditCard: 가로·세로 카드, 기본·대비·메탈 외형, 클릭·키보드 플립, React 상태 제어와 접근성 지원.
+
+- Ticket, BoardingPass, Receipt: 반응형 티켓·탑승권·영수증과 React 래퍼. 절취 형태, 코드 이미지, 안전한 정수 금액 계산, 지역화 및 액션 이벤트 지원.
+
+### 개선
+
+- Sidebar: `hideExpandIcon`·`showDepthGuide` 표시 옵션 추가. chevron 없이 카테고리를 열고 닫거나 하위 목록에 세로 가이드를 표시할 수 있습니다.
+
+- Sidebar: `children` 기반 2depth 내비게이션에 `expandedIds`·`accordionMode`·`db-expanded-change`/React `onExpandedChange`를 추가. 부모/하위 선택 스타일을 분리하고, 긴 목록 잘림을 제거. MenuItem은 native button과 `aria-expanded`/`aria-controls`, 접힌 하위 항목의 inert 처리, Enter·Space·좌우 방향키를 지원.
+
+- 최근32개 모듈 품질 검수: 인스턴스 CSS 간격 변수, 빈 폴더·단계 메타·의미 아이콘, 인용 top layer/닫힘/포커스, Vanilla 대화 append, 첨부 제거 포커스와 긴 멤버 목록의 모바일 배치를 개선. 새 런타임 의존성은 없다.
+
+- AI Elements: 18개 WC/React 모듈과 21개 참고 요소 대응 예제. 접이식 작업 추적·출처·승인·계획·실행 결과·대화, 기존 API/URL 유지. [사용 계약](./docs/AI-ELEMENTS.md).
+
+- 충전 모달을 라디오 없는 버튼 카드 선택으로 개선. 상품명 스타터/플러스/프로, 카드 내부 추천 배지, 좌측 결제 요약 제거. 기본 Recharge 동작과 controlled 이벤트는 유지.
+
+- 모듈형 헤더 크레딧 드롭다운·충전 모달과 실제 앱 조립 example 추가. native Popover 및 기존 Modal의 focus trap/portal을 사용하고 controlled 선택·요약/로딩·오류를 연결.
+
+- 크레딧 잔액/예약/사용·충전 선택/결제 진입·AI 작업 상태 Web Components와 React wrapper 추가. 실제 결제·크레딧 지급은 앱/서버가 담당. [연결 안내](./docs/CREDIT-AI.md).
+
+## 0.8.14 - 2026-10-22
+
+### 수정
+
+- `db-textarea`: 입력 중 `error`·`error-message` 가 바뀌면(예: 빈 값 제출 후 검증) 입력한 내용이 지워지거나 잘리던 문제 수정. 입력할 때마다 `value` 속성을 실제 값으로 맞춰 둔다.
+- `db-textarea`: 내부 `<textarea>` id 를 `<호스트 id>-field` 로 바꿔 호스트와 id 가 겹치지 않게 하고, 라벨이 실제 입력 필드를 가리키도록 수정.
+- `db-select`: 옵션에 `aria-disabled` 를 명시.
+
 ## 0.8.13 - 2026-10-12
 
 ### 개선

package/LICENSE-PAYMENT-LOGOS.md

@@ -0,0 +1,437 @@
+# Payment brand artwork
+
+Source: https://github.com/datatrans/payment-logos (assets/cards), retrieved 2026-10-21.
+Authors: Datatrans Ltd and repository contributors.
+Visa, Mastercard, American Express, Discover, JCB and UnionPay SVG artwork is distributed unchanged in src/assets/payment and encoded as data URLs in src/helpers/payment-brands.ts. The additional Visa and Mastercard cardSrc variants remove the white background rectangle and trim the viewBox; Visa is displayed as a monochrome CSS mask. These adaptations remain under CC BY-SA 4.0.
+License: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
+https://creativecommons.org/licenses/by-sa/4.0/
+Artwork and brand names remain trademarks of their respective owners. This notice concerns the artwork; the rest of the library retains its existing license.
+
+Attribution-ShareAlike 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+	wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More_considerations
+     for the public: 
+	wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution-ShareAlike 4.0 International Public
+License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You
+such rights in consideration of benefits the Licensor receives from
+making the Licensed Material available under these terms and
+conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. BY-SA Compatible License means a license listed at
+     creativecommons.org/compatiblelicenses, approved by Creative
+     Commons as essentially the equivalent of this Public License.
+
+  d. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  e. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  f. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  g. License Elements means the license attributes listed in the name
+     of a Creative Commons Public License. The License Elements of this
+     Public License are Attribution and ShareAlike.
+
+  h. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  i. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  j. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  k. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  l. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  m. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. Additional offer from the Licensor -- Adapted Material.
+               Every recipient of Adapted Material from You
+               automatically receives an offer from the Licensor to
+               exercise the Licensed Rights in the Adapted Material
+               under the conditions of the Adapter's License You apply.
+
+            c. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+  b. ShareAlike.
+
+     In addition to the conditions in Section 3(a), if You Share
+     Adapted Material You produce, the following conditions also apply.
+
+       1. The Adapter's License You apply must be a Creative Commons
+          license with the same License Elements, this version or
+          later, or a BY-SA Compatible License.
+
+       2. You must include the text of, or the URI or hyperlink to, the
+          Adapter's License You apply. You may satisfy this condition
+          in any reasonable manner based on the medium, means, and
+          context in which You Share Adapted Material.
+
+       3. You may not offer or impose any additional or different terms
+          or conditions on, or apply any Effective Technological
+          Measures to, Adapted Material that restrict exercise of the
+          rights granted under the Adapter's License You apply.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material,
+
+     including for purposes of Section 3(b); and
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

package/README.md

@@ -1,8 +1,8 @@
-# @designbasekorea/ui-wc
+# Supernormal Web Components
 
-Designbase **Web Components** — Vue 3, Angular, React, vanilla HTML에서 공통으로 사용하는 웹 컴포넌트 라이브러리입니다.
+Supernormal(슈퍼노말), by Designbase. **Web Components** — Vue 3, Angular, React, vanilla HTML에서 공통으로 사용하는 웹 컴포넌트 라이브러리입니다.
 
-100여 개의 커스텀 엘리먼트를 제공하며, React 전용 wrapper(`@designbasekorea/ui-wc/react`)도 포함합니다.
+커스텀 엘리먼트를 제공하며, React 전용 wrapper(`@designbasekorea/ui-wc/react`)도 포함합니다.
 
 ### 품질 규격
 
@@ -22,6 +22,10 @@ npm run audit:axe       # axe-core 런타임 접근성 검증 (build 선행 필
 npm run verify:docs     # 문서 ↔ 구현 정합성
 ```
 
+## 크레딧·충전·AI 작업 UI (개발 소스)
+
+`CreditBalance`, `CreditRecharge`, `AiTaskStatus`, `CreditDropdown`, `CreditRechargeModal`의 Web Component/React API와 서버 연결 경계는 [사용 안내](./docs/CREDIT-AI.md)를 따릅니다. 기존 배포 0.8.13에는 아직 포함되지 않은 추가 기능입니다.
+
 ## 최근 변경
 
 버전별 변경 내용은 [CHANGELOG.md](./CHANGELOG.md) 를 참고하세요.
@@ -183,6 +187,33 @@ property setter를 지원하는 컴포넌트: `db-tabs`, `db-navbar`, `db-sideba
 
 ---
 
+## Sidebar 2depth · 아코디언
+
+`sections[].items[].children`에 하위 항목을 넣으면 부모 아래에 들여쓴 2depth 목록이 펼쳐집니다. 부모 클릭은 열기/닫기, 하위 클릭은 기존 `db-item-click` 이벤트를 전달합니다. 라우팅은 앱에서 연결합니다.
+
+- `accordion-mode="single"` (기본): 한 그룹씩 열기. `multiple`: 여러 그룹 열기.
+- `hide-expand-icon` / React `hideExpandIcon`: chevron 숨김. 펼침 상태의 ARIA와 키보드 동작은 유지됩니다.
+- `show-depth-guide` / React `showDepthGuide`: 하위 목록 왼쪽에 의미 토큰 기반 세로 가이드 표시. 두 옵션은 기본적으로 꺼져 있습니다.
+- `default-expanded-ids`: 초기 그룹 ID의 JSON 배열.
+- `expanded-ids` / `expandedIds`: 현재 펼침 상태를 외부에서 지정하는 배열/JSON. 선택된 `active` 항목과 독립적입니다.
+- `db-expanded-change`: `{ itemId, expanded, expandedIds }`. 사용자 조작 시 한 번 발생합니다. 속성으로 상태를 지정할 때는 발생하지 않습니다.
+- Enter·Space로 열기/닫기, →로 열기, ←로 닫기. 닫힌 하위 목록은 키보드와 접근성 탐색에서 제외됩니다. 열린 목록은 고정 높이로 잘리지 않습니다.
+
+```tsx
+const [expandedIds, setExpandedIds] = useState(['form']);
+<Sidebar
+    sections={[{ id: 'library', items: [{ id: 'form', label: 'Form', children: [
+        { id: 'button', label: 'Button' }, { id: 'input', label: 'Input', active: true },
+    ] }] }]}
+    accordionMode="single"
+    expandedIds={expandedIds}
+    onExpandedChange={event => setExpandedIds(event.detail.expandedIds)}
+    onItemClick={event => navigate(`/components/${event.detail.item.id}`)}
+/>
+```
+
+자체적으로 HTML 아코디언을 중복 구현할 필요가 없습니다. 앱은 메뉴 데이터·선택·라우팅을 맡고 Sidebar는 2depth 표현·펼침·키보드 동작을 담당합니다.
+
 ## Sidebar 커스텀 내비게이션
 
 `db-sidebar`의 메인 영역에는 데이터 기반 `items`·`sections`와 함께 커스텀 콘텐츠를 넣을 수 있습니다.
@@ -482,3 +513,20 @@ import { NavigationRail } from '@designbasekorea/ui-wc/react';
 ```
 
 툴팁을 직접 구성할 때 `db-tooltip focus-target="child"`를 지정하면 내부 버튼/링크에 포커스를 유지하고 wrapper의 추가 Tab 정지를 없앱니다.
+
+AI 대화·작업 과정·출처·도구 결과는 [AI Elements](./docs/AI-ELEMENTS.md)를 참고하세요.
+
+### 티켓 · 탑승권 · 영수증
+
+`db-ticket` / `Ticket`, `db-boarding-pass` / `BoardingPass`, `db-receipt` / `Receipt`를 제공합니다. 객체 데이터, container query 기반 반응형 배치, 절취 모양, 실제 코드 이미지, 지역화와 정수 금액 계산을 지원합니다. [사용법과 데이터 계약](docs/PAPER-CARDS.md)을 참고하세요.
+
+### 신용카드 표시
+
+`db-credit-card` / `CreditCard`: 가로·세로 비율, 클릭·키보드 앞뒷면 전환, 상태 제어와 동작 줄이기 설정을 지원합니다. [데이터 API와 사용법](docs/CREDIT-CARD.md)을 참고하세요.
+
+
+## 컴포넌트 패키지만 배포
+
+저장소 루트에서 `npm run ui-wc:build`로 공유 계약과 ui-wc만 빌드하고, `npm run publish:ui-wc`로 `@designbasekorea/ui-wc`만 npm에 배포합니다. 이 명령은 blocks·템플릿·갤러리를 배포하지 않습니다. 갤러리 전체 빌드는 `npm run example:gallery:build`가 blocks 빌드를 별도로 실행합니다.
+
+npm 배포물에는 ui-wc의 `dist`, README·변경 이력과 결제 로고 라이선스 고지만 포함됩니다. 신규 컴포넌트는 전체 진입점·React 래퍼·개별 import에서 사용할 수 있습니다. 결제·초대·AI 요청·저장 같은 실제 서버 동작은 소비 앱에서 연결합니다.

package/dist/esm/components/db-achievement-list.d.ts

@@ -0,0 +1,31 @@
+import { DbElement } from '../core/base-element.js';
+import './db-button.js';
+
+interface DbAchievementItem {
+    id: string;
+    title: string;
+    description: string;
+    state: 'locked' | 'earned' | 'needs_review';
+    current?: number;
+    target?: number;
+    earnedLabel?: string;
+    motif?: 'star' | 'award' | 'bulb' | 'heart';
+}
+/** Presentation only. The owner supplies server-validated awards/progress; selection grants nothing. */
+declare class DbAchievementList extends DbElement {
+    private data;
+    static get observedAttributes(): string[];
+    get items(): DbAchievementItem[];
+    set items(value: DbAchievementItem[]);
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private render;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'db-achievement-list': DbAchievementList;
+    }
+}
+
+export { DbAchievementList };
+export type { DbAchievementItem };

package/dist/esm/components/db-achievement-list.js

@@ -0,0 +1 @@
+import{DbElement as t}from"../core/base-element.js";import{textNode as e,replaceView as i}from"../core/credit-ui.js";import{createDbIcon as s}from"./db-icons.js";import"./db-button.js";function achievementItems(t){const e=new Set;return Array.isArray(t)?t.filter(t=>!(!t||"string"!=typeof t.id||!t.id||e.has(t.id)||"string"!=typeof t.title||"string"!=typeof t.description||!["locked","earned","needs_review"].includes(t.state))&&(e.add(t.id),!0)).map(t=>({id:t.id,title:t.title,description:t.description,state:t.state,current:Number.isSafeInteger(t.current)&&t.current>=0?t.current:void 0,target:Number.isSafeInteger(t.target)&&t.target>0?t.target:void 0,earnedLabel:"string"==typeof t.earnedLabel?t.earnedLabel:void 0,motif:["star","award","bulb","heart"].includes(t.motif||"")?t.motif:"award"})):[]}function achievementMedallion(t){const i=e("div","designbase-wc-achievement-art","");return i.dataset.state=t.state,i.setAttribute("aria-hidden","true"),i.append(s(t.motif||"award",40)),i}class DbAchievementList extends t{constructor(){super(...arguments),this.data=[]}static get observedAttributes(){return["label","empty-label","loading","error"]}get items(){return this.data.map(t=>({...t}))}set items(t){this.data=achievementItems(t),this.isConnected&&this.render()}connectedCallback(){this.upgradeProperties(["items"]),this.cleanups.listen(this,"db-click",t=>{const e=t.target instanceof HTMLElement?t.target.closest("[data-badge-id]"):null;e&&this.contains(e)&&!this.hasAttribute("loading")&&!this.hasAttribute("error")&&this.dbEmit("select",{id:e.dataset.badgeId})}),this.render()}attributeChangedCallback(){this.isConnected&&this.render()}render(){this.classList.add("designbase-wc-achievement-list"),this.setAttribute("aria-busy",String(this.hasAttribute("loading")));const t=e("div","designbase-wc-achievement-list__grid","");t.setAttribute("role","list"),t.setAttribute("aria-label",this.getAttribute("label")||"뱃지 목록");const s=this.getAttribute("error")||(this.hasAttribute("loading")?"뱃지를 불러오고 있어요":this.data.length?"":this.getAttribute("empty-label")||"아직 등록된 뱃지가 없어요");if(s){const t=e("p","designbase-wc-achievement-list__message",s);return t.setAttribute("role",this.hasAttribute("error")?"alert":"status"),void i(this,t)}for(const i of this.data){const s=e("article","designbase-wc-achievement-list__card","");if(s.dataset.state=i.state,s.setAttribute("role","listitem"),s.append(achievementMedallion(i),e("span","designbase-wc-achievement-list__state","earned"===i.state?"획득 완료":"needs_review"===i.state?"기록 확인 필요":"도전 중"),e("h3","",i.title),e("p","designbase-wc-achievement-list__description",i.description)),"locked"===i.state&&i.target){const t=document.createElement("progress");t.max=i.target,t.value=Math.min(i.current||0,i.target),t.setAttribute("aria-label",i.title+" 진행률"),s.append(t,e("span","designbase-wc-achievement-list__date",`${Math.min(i.current||0,i.target)} / ${i.target}`))}else s.append(e("span","designbase-wc-achievement-list__date","earned"===i.state?i.earnedLabel||"나의 컬렉션에 담았어요":"needs_review"===i.state?"연결된 기록을 다시 확인해 주세요":"다음 순간을 기다려요"));const a=document.createElement("db-button");a.setAttribute("variant","secondary"),a.setAttribute("size","s"),a.dataset.badgeId=i.id,a.dataset.action=i.id,a.textContent="자세히 보기",a.setAttribute("aria-label",i.title+" 자세히 보기"),s.append(a),t.append(s)}i(this,t)}}customElements.get("db-achievement-list")||customElements.define("db-achievement-list",DbAchievementList);export{DbAchievementList,achievementItems,achievementMedallion};

package/dist/esm/components/db-achievement-modal.d.ts

@@ -0,0 +1,38 @@
+import { DbElement } from '../core/base-element.js';
+import { DbAchievementItem } from './db-achievement-list.js';
+import './db-modal.js';
+import './db-confetti.js';
+import './db-button.js';
+
+/** Controlled presentation; no award or receipt writes. Effects stay inside this modal. */
+declare class DbAchievementModal extends DbElement {
+    private data;
+    private modal?;
+    private body?;
+    private confetti?;
+    private frame;
+    private viewKey;
+    private presentationKey;
+    private readonly descriptionId;
+    private readonly headingId;
+    static get observedAttributes(): string[];
+    get items(): DbAchievementItem[];
+    set items(value: DbAchievementItem[]);
+    get open(): boolean;
+    set open(value: boolean);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private dismiss;
+    private stopEffects;
+    private ensureView;
+    private stage;
+    private sync;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'db-achievement-modal': DbAchievementModal;
+    }
+}
+
+export { DbAchievementModal };

package/dist/esm/components/db-achievement-modal.js

@@ -0,0 +1 @@
+import{DbElement as t}from"../core/base-element.js";import{textNode as e,creditAction as i,replaceView as s}from"../core/credit-ui.js";import{dbUid as a}from"../core/uid.js";import{achievementItems as n,achievementMedallion as o}from"./db-achievement-list.js";import"./db-modal.js";import"./db-confetti.js";import"./db-button.js";class DbAchievementModal extends t{constructor(){super(...arguments),this.data=[],this.frame=null,this.viewKey="",this.presentationKey="",this.descriptionId=a("achievement-description"),this.headingId=a("achievement-heading")}static get observedAttributes(){return["open","mode","loading","error","confirm-label"]}get items(){return this.data.map(t=>({...t}))}set items(t){this.data=n(t),this.isConnected&&this.sync()}get open(){return this.hasAttribute("open")&&"false"!==this.getAttribute("open")}set open(t){this.toggleAttribute("open",t)}connectedCallback(){this.upgradeProperties(["items","open"]),this.ensureView(),this.cleanups.listen(this.modal,"db-close",t=>{t.stopPropagation(),this.dismiss(),queueMicrotask(()=>{this.isConnected&&this.open&&this.modal&&!this.modal.open&&(this.modal.open=!0)})}),this.cleanups.listen(this.body,"db-click",t=>{t.target instanceof HTMLElement&&["acknowledge","dismiss"].includes(t.target.dataset.action||"")&&this.dismiss()}),this.cleanups.listen(window.matchMedia("(prefers-reduced-motion: reduce)"),"change",()=>{this.stopEffects(),this.viewKey="",this.sync()}),this.sync()}disconnectedCallback(){this.stopEffects(),this.modal?.remove(),this.modal=void 0,this.viewKey="",this.presentationKey="",super.disconnectedCallback()}attributeChangedCallback(){this.isConnected&&this.sync()}dismiss(){!this.hasAttribute("loading")&&this.open&&this.dbEmit("dismiss",{ids:this.data.map(t=>t.id)})}stopEffects(){null!==this.frame&&cancelAnimationFrame(this.frame),this.frame=null,this.confetti?.remove(),this.confetti=void 0}ensureView(){this.modal||(this.modal=document.createElement("db-modal"),this.modal.setAttribute("size","s"),this.body=e("div","designbase-wc-achievement-modal__body",""),this.body.setAttribute("data-modal-part","body"),this.modal.append(this.body),this.append(this.modal))}stage(t){const i=e("div","designbase-wc-achievement-modal__stage","");i.setAttribute("aria-hidden","true"),this.open&&"earned"===t.state&&!window.matchMedia("(prefers-reduced-motion: reduce)").matches&&(this.confetti=document.createElement("db-confetti"),this.confetti.setAttribute("trigger","manual"),i.append(this.confetti));const s=e("div","designbase-wc-achievement-modal__coin","");s.dataset.state=t.state;for(let t=-5;t<=5;t++){const i=e("span","designbase-wc-achievement-modal__edge","");i.style.transform=`translateZ(${t}px)`,s.append(i)}const a=o(t);a.classList.add("designbase-wc-achievement-modal__face","designbase-wc-achievement-modal__face--front");const n=o(t);return n.classList.add("designbase-wc-achievement-modal__face","designbase-wc-achievement-modal__face--back"),s.append(a,n),i.append(s),i}sync(){if(!this.modal||!this.body)return;const t=this.data[0],a="detail"!==this.getAttribute("mode");this.modal.removeAttribute("title"),this.modal.setAttribute("describedby",this.descriptionId),this.modal.setAttribute("show-close-button","false");for(const t of["close-on-escape","close-on-outside-click"])this.modal.setAttribute(t,String(!this.hasAttribute("loading")));const n=JSON.stringify([this.data,a,this.open,this.hasAttribute("loading"),this.getAttribute("error"),this.getAttribute("confirm-label")]);if(n!==this.viewKey){this.viewKey=n,this.stopEffects();const o=document.createElement("div"),d=i("dismiss","",this.hasAttribute("loading"));if(d.classList.add("designbase-wc-achievement-modal__close"),d.setAttribute("variant","ghost"),d.setAttribute("start-icon","close"),d.setAttribute("icon-only",""),d.setAttribute("aria-label","모달 닫기"),o.append(d),t){o.append(this.stage(t),e("span","designbase-wc-achievement-modal__eyebrow","locked"===t.state?"아직 획득하지 못한 뱃지":"needs_review"===t.state?"기록 확인 필요":a?"새로운 순간을 모았어요":"나의 컬렉션"));const i=e("h3","",t.title);i.id=this.headingId,o.append(i);const s=e("p","designbase-wc-achievement-modal__description",t.description);if(s.id=this.descriptionId,o.append(s),t.earnedLabel&&"earned"===t.state&&o.append(e("p","designbase-wc-achievement-list__date",t.earnedLabel)),this.data.length>1){const t=e("div","designbase-wc-achievement-modal__related","함께 받은 뱃지 "+(this.data.length-1)+"개");for(const i of this.data.slice(1))t.append(e("span","",i.title));o.append(t)}}else{const t=e("p","","표시할 뱃지가 없어요");t.id=this.descriptionId,o.append(t)}const c=e("p","designbase-wc-achievement-modal__error",this.getAttribute("error")||"");c.setAttribute("role","alert"),c.hidden=!c.textContent,o.append(c);const r=this.getAttribute("confirm-label")||("locked"===t?.state?"아직 획득하지 못했어요":"확인"),h=i("acknowledge",r,this.hasAttribute("loading"));h.setAttribute("variant","locked"===t?.state?"secondary":"primary"),h.setAttribute("size","m"),h.toggleAttribute("loading",this.hasAttribute("loading")),o.append(h),s(this.body,...Array.from(o.childNodes))}this.modal.open!==this.open&&(this.modal.open=this.open);const o=this.body.closest('[role="dialog"]');o?.classList.add("designbase-wc-achievement-modal__panel"),t&&o?.setAttribute("aria-labelledby",this.headingId);const d=JSON.stringify([this.data.map(t=>[t.id,t.state]),a]);this.open?this.presentationKey!==d&&(this.presentationKey=d,this.frame=requestAnimationFrame(()=>{if(this.frame=null,this.open&&this.isConnected&&this.confetti)for(const[t,e]of[[.08,65],[.92,115]])this.confetti.fire({particleCount:42,origin:{x:t,y:.88},angle:e,spread:75,startVelocity:26,ticks:140,scalar:.75,disableForReducedMotion:!0})})):(this.presentationKey="",this.stopEffects())}}customElements.get("db-achievement-modal")||customElements.define("db-achievement-modal",DbAchievementModal);export{DbAchievementModal};