@iyulab/data-components 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,7 +1,106 @@
 # Changelog
 
+## [0.13.0] - 2026-08-05
+
+### Added
+
+- **Agent skill pack ships with the package** (`skills/iyulab-data-components`).
+  Until now the only way to learn the API was to read the emitted `.d.ts` files, which
+  made the internal file layout a de-facto contract and left the *combinations* — server
+  paging together with selection — undocumented. The reference for `u-rich-table` opens
+  with the two things that actually bite: every row needs a unique `_id` (without it a
+  single selection looks like "everything is selected"), and the app owns the query
+  (`totalCount` is not `data.length`).
+
+  ```bash
+  npx skills add ./node_modules/@iyulab/data-components/skills/iyulab-data-components
+  ```
+
+- **The public types `u-rich-table` asks for are exported from the package root** —
+  `ColumnDef`, `CellPosition`, `SortState`, `FilterState`, `RichTableEventMap`.
+  `columns` requires `ColumnDef[]`, but that name could not be imported from the root, so
+  consumers had to deep-import an internal path or hand-copy the shape (which then drifts
+  silently when the upstream type changes).
+
+  ```ts
+  import type { ColumnDef, RichTableEventMap } from '@iyulab/data-components';
+  ```
+
+### Fixed
+
+- **`u-data-view`: the layout toggle buttons did nothing.** Grid / list / table were
+  rendered but never wired to a click handler, so `mode` could only be changed by setting
+  the property — and the "selected" highlight was therefore stuck on `grid` forever.
+  The buttons now switch the layout and expose their state via `aria-pressed`.
+
+### Removed
+
+- **`u-data-view`: unreachable selected-row styling.** The `.selected` rules were driven
+  by an internal index that was never assigned, so they could not apply. Removed along
+  with the dead state.
+
+## [0.12.0] - 2026-08-04
+
+### Fixed
+
+- 🔴**`u-rich-table` 의 전체선택이 다른 페이지의 선택을 조용히 파괴했다.** 서버 페이징
+  (`totalCount`/`currentPage`/`page-change`)에서 선택 상태는 페이지를 넘어 유지되는데,
+  전체선택 체크박스만 그 사실을 모르고 있었다:
+  - 체크 상태를 **«누적 선택 수 == 이 페이지 행 수»** 로 계산했다 ⇒ 1페이지를 전량 선택하고
+    2페이지로 넘어가면 **아무것도 고르지 않았는데 켜져 보였다.**
+  - 그 상태에서 체크박스를 끄면 선택 집합을 **통째로 비웠다** ⇒ 사용자에게는 *"이 페이지 해제"*
+    로 보이는 조작이 1페이지의 선택을 말없이 지웠다.
+  - 켜는 쪽도 합집합이 아니라 **치환**이었다 ⇒ 2페이지에서 전체선택하면 1페이지 선택분이 사라졌다.
+    `Ctrl`/`Cmd` + `A` 도 같은 경로였다.
+
+  ⇒ 전체선택/해제의 범위를 **현재 페이지**로 확정했다(합집합·차집합). 체크박스의 분자와 분모가
+  모두 현재 페이지 기준이 되어, 다른 페이지의 선택분이 이 페이지의 표시로 새지 않는다.
+
+  ⚠**단일 페이지 사용(`totalCount = 0`)에서는 동작이 종전과 완전히 같다** — 현재 페이지가
+  곧 전체이므로 합집합·차집합이 치환·전역소거와 일치한다.
+
+### Added
+
+- **선택 집합을 읽고 쓸 수 있다** — 종전에는 선택 상태가 `private` 이라 소비앱이 «해제»와
+  «다른 페이지에 있음»을 구분할 방법이 없었고, 그래서 추정할 수밖에 없었다.
+  - **`selectedRowIds`** *(getter)* — 페이지를 가로질러 누적된 **모든** 선택 식별자.
+    `getSelectedRows()` 는 현재 페이지의 행 객체만 주므로(갖고 있지 않은 행을 만들 수 없다)
+    *"여러 페이지에 걸쳐 고른 뒤 일괄 처리"* 에는 이쪽이 필요하다. **스냅샷**이라 돌려받은
+    집합을 고쳐도 내부 상태가 흔들리지 않는다.
+  - **`setSelection(ids)`** — 선택을 통째로 대체한다. 현재 페이지에 없는 식별자도 받는다.
+    ⚠**같은 집합이면 아무 일도 하지 않는다** — `selection-change` 를 받아 앱 상태를 갱신하고
+    다시 이것을 부르는 배선이 자연스러운데, 무조건 발생시키면 그 자리가 무한 루프가 된다.
+  - **`clearSelection()`** — 누적분까지 전부 비운다. 전체선택 체크박스가 «이 페이지» 범위가
+    되면서 전역 소거의 자리가 없어졌고, 일괄 처리 후 앱이 상태를 되돌리는 경로가 여기다.
+- **`selection-change` detail 에 `selectedIds: string[]` 추가** — `selectedRows`(현재 페이지)와
+  나란히 누적 식별자를 싣는다. 두 필드의 길이가 다른 것이 서버 페이징에서는 정상이다.
+- **`select-all` 이벤트** — 사용자가 전체선택 체크박스를 조작했다는 **의도**를 따로 알린다.
+  `selection-change` 만으로는 *"세 행을 골랐다"* 와 *"전체선택을 눌렀다"* 가 구분되지 않는데,
+  서버 페이징에서 후자는 앱이 *"조건에 맞는 N건 전부"* 를 제안할 자리다.
+  ⚠**`scope: 'page' | 'all'` 필드는 두지 않았다** — 이 컴포넌트는 `'all'` 을 낼 수 없다.
+  전역 전체선택은 식별자 목록이 아니라 **조회 조건**이라 컴포넌트가 표현할 수 있는 것이 아니고,
+  값이 하나뿐인 유니온은 라이브러리가 모르는 개념을 아는 척하는 필드가 된다.
+
+### Changed
+
+- **선택 건수 라벨이 두 숫자를 구분해 알린다** — 선택이 페이지를 가로지르면
+  `4 selected (1 on this page)` 처럼 누적과 이 페이지 몫을 함께 낸다. 한 페이지 안에 머무는
+  동안에는 종전대로 `3 selected` 다. 두 숫자가 다르다는 사실 자체가 사용자에게 보여야 한다.
+- **선택 건수·페이지 크기 문구가 로케일 레지스트리로 이주했다**(`selected` ·
+  `selectedAcrossPages` · `rowsPerPage`). `0.11.0` 의 이주가 중첩 템플릿 안의 두 건을
+  남겨 두어, 다른 문구가 전부 영어인 환경에서 이 둘만 한국어로 나왔다.
+
 ## [0.11.0] - 2026-08-04
 
+### Fixed
+
+- 🔴**`LICENSE` 파일이 없어 게시본에 MIT 원문이 빠져 있었다.** `package.json` 이
+  `"license": "MIT"` 를 선언하고 `files` 에 `LICENSE` 를 나열했지만 파일 자체가 없었다
+  ⇒ `0.10.0` 까지의 tarball 에 라이선스 원문이 들어 있지 않다. MIT 는 *"위 저작권 고지와
+  이 허가 고지를 모든 사본에 포함시켜야 한다"* 는 조건부 허가이므로, 원문 누락은 그 조건을
+  스스로 이행하지 못한 상태였다. ⚠`npm view … license` 가 `MIT` 를 보여 주는 것은
+  `package.json` 필드를 읽은 것이지 **원문이 배포됐다는 뜻이 아니다.**
+
 ### Changed
 
 - **`u-rich-table` 의 `_id` 부재 경고가 영어로 이주했다** — 개발자 대면 진단이므로 로케일

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 iyulab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -18,6 +18,23 @@
 npm install @iyulab/data-components
 ```
 
+## 🤖 Skills Usage
+
+이 패키지는 AI 코딩 에이전트가 라이브러리를 이해하고 사용하도록 돕는
+[Agent Skill](https://agentskills.io/)을 포함합니다.
+
+**GitHub 경유 (권장):**
+
+```bash
+npx skills add iyulab/node-data-components
+```
+
+**로컬 `node_modules` 경유:**
+
+```bash
+npx skills add ./node_modules/@iyulab/data-components/skills/iyulab-data-components
+```
+
 ## Quick Start
 
 ### USimpleSheet

package/dist/components/data-view/UDataView.d.ts

@@ -34,9 +34,17 @@ export declare class UDataView extends UElement {
     renderCard?: (item: DataItem, index: number) => TemplateResult;
     /** 커스텀 셀 렌더 함수 (table용) */
     renderCell?: (item: DataItem, column: DataColumn, index: number) => TemplateResult | string;
-    private selectedIndex;
     render(): TemplateResult<1>;
     private renderToolbar;
+    /**
+     * 레이아웃 전환 버튼.
+     *
+     * ⚠**선택 상태를 `variant`+`color` 로 나타낸다.** 종전에는 `?active` 로 이 시트의
+     * `u-button[active]` 규칙(배경 한 줄)을 켰는데, 그 규칙은 자기 주석에 *"주색 위의 글자
+     * 대비가 3.45~3.68 로 최선이 아니다"* 라고 적고 있었다. `UButton` 자신의 `variant`·`color`
+     * 를 쓰면 그 대비 계약을 컴포넌트가 책임진다.
+     * 접근성은 `aria-pressed` 가 나른다 — 색만으로는 토글 상태가 보조기술에 닿지 않는다.
+     */
     private renderViewButton;
     private renderContent;
     private renderGrid;

package/dist/components/data-view/UDataView.js

@@ -2,7 +2,7 @@ import { styles } from "./UDataView.styles.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 { html } from "lit";
-import { customElement, property, state } from "lit/decorators.js";
+import { customElement, property } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 import "@iyulab/components/dist/components/button/UButton.js";
 import { UElement } from "@iyulab/components/dist/components/UElement.js";
@@ -14,7 +14,6 @@ var UDataView = class UDataView extends UElement {
 		this.mode = "grid";
 		this.gridMinWidth = "200px";
 		this.gap = "1rem";
-		this.selectedIndex = null;
 	}
 	static {
 		this.styles = [super.styles, styles];
@@ -41,11 +40,27 @@ var UDataView = class UDataView extends UElement {
       </div>
     `;
 	}
+	/**
+	* 레이아웃 전환 버튼.
+	*
+	* ⚠**선택 상태를 `variant`+`color` 로 나타낸다.** 종전에는 `?active` 로 이 시트의
+	* `u-button[active]` 규칙(배경 한 줄)을 켰는데, 그 규칙은 자기 주석에 *"주색 위의 글자
+	* 대비가 3.45~3.68 로 최선이 아니다"* 라고 적고 있었다. `UButton` 자신의 `variant`·`color`
+	* 를 쓰면 그 대비 계약을 컴포넌트가 책임진다.
+	* 접근성은 `aria-pressed` 가 나른다 — 색만으로는 토글 상태가 보조기술에 닿지 않는다.
+	*/
 	renderViewButton(mode, icon, label) {
+		const selected = this.mode === mode;
 		return html`
       <u-button
-        ?active=${this.mode === mode}
+        variant=${selected ? "solid" : "ghost"}
+        color=${selected ? "primary" : "neutral"}
         title=${label}
+        aria-label=${label}
+        aria-pressed=${selected ? "true" : "false"}
+        @click=${() => {
+			this.mode = mode;
+		}}
       >
         <u-icon lib="bootstrap" name=${icon}></u-icon>
       </u-button>
@@ -89,9 +104,7 @@ var UDataView = class UDataView extends UElement {
           </thead>
           <tbody>
             ${this.items.map((item, index) => html`
-              <tr 
-                class=${this.selectedIndex === index ? "selected" : ""}
-              >
+              <tr>
                 ${cols.map((col) => html`
                   <td>${this.getCellContent(item, col, index)}</td>
                 `)}
@@ -105,9 +118,7 @@ var UDataView = class UDataView extends UElement {
 	renderGridItem(item, index) {
 		const content = this.renderCard ? this.renderCard(item, index) : this.renderDefaultCard(item);
 		return html`
-      <div 
-        class="card ${this.selectedIndex === index ? "selected" : ""}"
-      >
+      <div class="card">
         ${content}
       </div>
     `;
@@ -115,9 +126,7 @@ var UDataView = class UDataView extends UElement {
 	renderListItem(item, index) {
 		const content = this.renderCard ? this.renderCard(item, index) : this.renderDefaultCard(item);
 		return html`
-      <div 
-        class="card list-card ${this.selectedIndex === index ? "selected" : ""}"
-      >
+      <div class="card list-card">
         ${content}
       </div>
     `;
@@ -168,7 +177,6 @@ __decorate([property({ type: String }), __decorateMetadata("design:type", Object
 __decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UDataView.prototype, "gap", void 0);
 __decorate([property({ attribute: false }), __decorateMetadata("design:type", Function)], UDataView.prototype, "renderCard", void 0);
 __decorate([property({ attribute: false }), __decorateMetadata("design:type", Function)], UDataView.prototype, "renderCell", void 0);
-__decorate([state(), __decorateMetadata("design:type", Object)], UDataView.prototype, "selectedIndex", void 0);
 UDataView = __decorate([customElement("u-data-view")], UDataView);
 //#endregion
 export { UDataView };

package/dist/components/data-view/UDataView.styles.js

@@ -44,15 +44,10 @@ var styles = [css`
     gap: 0.25rem;
   }
 
-  .view-toggles u-button[active] {
-    background: var(--u-primary-color, #1976D2);
-    /* 예외 1 — "주색 위의 글자" 역할 토큰이 없다.
-       역할 층의 유채색은 전경 5단(--u-primary-color-*)뿐이고, 그 위에 얹는 글자색을
-       가리키는 토큰은 없다. 실측: 라이트 #FFFFFF/#1E88E5 = 3.68, 다크 #000000/#2A659D
-       = 3.45 — 다크는 흰 글자였다면 6.09 였다. 즉 현재 값이 최선이 아니지만, 팔레트를
-       직접 바꾸면 게시된 시각이 움직이므로 토큰 추가 결정까지 현행을 유지한다. */
-    color: var(--u-neutral-0, #FFFFFF);
-  }
+  /* 선택된 레이아웃 버튼의 표기는 UButton 의 variant+color 가 맡는다(cycle-244).
+     종전의 u-button[active] 규칙은 배경만 바꾸면서 그 위 글자 대비가 3.45~3.68 이라고
+     스스로 적고 있었다 — 컴포넌트의 색 계약을 우회하지 않고 그쪽에 위임한다.
+     (주석 안 백틱 금지: css 태그드 템플릿을 그 자리에서 끝낸다) */
 
   .info {
     font-size: 0.875rem;
@@ -90,12 +85,6 @@ var styles = [css`
     transform: translateY(-2px);
   }
 
-  .card.selected {
-    border-color: var(--u-primary-color, #1976D2);
-    background: var(--u-bg-color-active, #EEEEEE);
-    box-shadow: 0 0 0 3px var(--u-primary-color-weakest, #90CAF9);
-  }
-
   .card-content {
     display: flex;
     flex-direction: column;
@@ -177,10 +166,6 @@ var styles = [css`
     background: var(--u-bg-color-hover, #F5F5F5);
   }
 
-  tbody tr.selected {
-    background: var(--u-bg-color-active, #EEEEEE);
-  }
-
   tbody tr:not(:last-child) {
     border-bottom: 1px solid var(--u-border-color-weak, #EEEEEE);
   }

package/dist/components/u-rich-table/URichTable.d.ts

@@ -40,6 +40,35 @@ export declare class URichTable extends LitElement {
     revertRow(_rowId: string): void;
     setRowError(rowId: string, message: string): void;
     clearRowError(rowId: string): void;
+    /**
+     * 선택된 행의 **식별자 집합** — 페이지를 가로질러 누적된 전부.
+     *
+     * `getSelectedRows()` 는 현재 페이지의 행 객체만 돌려주므로(갖고 있지 않은 행을 만들 수 없다)
+     * *"여러 페이지에 걸쳐 고른 뒤 일괄 처리"* 에는 이쪽이 필요하다.
+     *
+     * ⚠**스냅샷이다.** 내부 집합을 그대로 넘기면 `ReadonlySet` 이 타입 수준 약속일 뿐이라
+     * JS 소비자가 `add` 로 내부 상태를 **갱신 신호 없이** 망가뜨릴 수 있다. 복제 비용은
+     * 선택 크기에 비례하고 무시할 수준이다.
+     */
+    get selectedRowIds(): ReadonlySet<string>;
+    /**
+     * 선택을 **통째로 대체**한다 — 페이지를 가로지르는 누적분까지.
+     *
+     * 앱이 자기 상태를 정본으로 삼는 경우(외부 저장·복원, 필터 변경 시 정리)의 진입점이다.
+     * 현재 페이지에 없는 식별자를 넣어도 된다 — 그 페이지로 이동하면 선택된 것으로 렌더된다.
+     *
+     * ⚠**같은 집합이면 아무 일도 하지 않는다.** 앱이 `selection-change` 를 받아 자기 상태를
+     * 갱신하고 다시 이것을 부르는 것이 자연스러운 배선인데, 무조건 발생시키면 그 자리가
+     * **무한 루프**가 된다.
+     */
+    setSelection(ids: Iterable<string>): void;
+    /**
+     * 선택을 **전부** 비운다 — 페이지를 가로지르는 누적분까지.
+     *
+     * 전체선택 체크박스는 «이 페이지»만 다루므로 전역 소거의 자리가 없다. 일괄 처리를 끝낸 뒤
+     * 앱이 상태를 되돌리는 경로가 여기다. `selection-change` 를 발생시킨다.
+     */
+    clearSelection(): void;
     /**
      * 행의 식별자. 선택·확장·행 오류 상태가 전부 이 값으로 추적된다.
      *
@@ -52,8 +81,24 @@ export declare class URichTable extends LitElement {
     private _rowId;
     private _warnedMissingRowId;
     private _warnMissingRowId;
+    /**
+     * **현재 페이지의** 선택된 행. 서버 페이징에서 다른 페이지의 선택분은 여기 없다 —
+     * 이 컴포넌트가 갖고 있지 않은 행을 돌려줄 수는 없기 때문이다.
+     * 페이지를 가로지르는 선택 집합이 필요하면 {@link selectedRowIds} 를 쓴다.
+     */
     getSelectedRows(): Record<string, unknown>[];
+    /** 이 페이지 행들의 식별자. 전체선택/해제가 «이 페이지» 범위임을 정의하는 값이다. */
+    private _pageRowIds;
+    /** 현재 페이지에서 선택된 행 수 — 전체선택 체크박스의 «분자». */
+    private get _selectedOnPage();
     render(): TemplateResult;
+    /**
+     * ⚠**두 숫자를 섞지 않는다.** 체크박스는 «이 페이지»를 켜고 끄므로 그 상태도 페이지 기준이고,
+     * 라벨의 건수는 페이지를 가로지르는 **누적**이다. 종전에는 분자만 누적이고 분모가 페이지라
+     * 다른 페이지의 선택분이 이 페이지의 체크 상태로 새어 나왔다 — 페이지 1을 전량 선택하고
+     * 넘어가면 페이지 2에서 아무것도 고르지 않았는데 체크박스가 켜져 보였고, 그것을 끄면
+     * 페이지 1의 선택이 조용히 사라졌다.
+     */
     private _renderToolbar;
     private _renderHeader;
     private _renderFilterRow;
@@ -62,6 +107,23 @@ export declare class URichTable extends LitElement {
     private _renderCellContent;
     private _renderNewRow;
     private _renderPagination;
+    /**
+     * 전체선택 체크박스 — 범위는 **현재 페이지**다(합집합/차집합, 치환이 아니다).
+     * 종전에는 켤 때 `new Set(현재 페이지)` 로 **치환**하고 끌 때 `new Set()` 으로 **전역 소거**해서,
+     * 어느 쪽이든 다른 페이지의 선택분이 함께 날아갔다. 전역 소거가 필요하면 {@link clearSelection}.
+     *
+     * ## 왜 `select-all` 을 따로 내보내는가
+     *
+     * `selection-change` 만으로는 *"사용자가 세 행을 골랐다"* 와 *"사용자가 전체선택을 눌렀다"* 가
+     * 구분되지 않는다. 서버 페이징에서 그 구분은 앱에 필요하다 — 전체선택을 누른 순간이
+     * *"이 조건에 맞는 N건 전부"* 를 제안할 자리이기 때문이다.
+     *
+     * ⚠**`scope: 'page' | 'all'` 필드는 두지 않았다.** 이 컴포넌트는 `'all'` 을 **낼 수 없다** —
+     * 다른 페이지의 행을 갖고 있지 않고, 서버 페이징에서 «전역 전체선택»은 id 목록이 아니라
+     * **조회 조건**이라 컴포넌트가 표현할 수 있는 것이 아니다. 값이 하나뿐인 유니온은
+     * *"라이브러리가 모르는 개념을 아는 척하는"* 필드가 된다. ⇒ 컴포넌트는 **의도만** 알리고
+     * 전역 해석은 앱이 한다.
+     */
     private _onSelectAll;
     private _onRowSelect;
     private _lastSelectedIndex;
@@ -83,6 +145,12 @@ export declare class URichTable extends LitElement {
     private _getOptionLabel;
     private _getPageNumbers;
     private _moveToNextEditableCell;
+    /**
+     * ⚠**두 필드가 서로 다른 것을 센다.** `selectedRows` 는 **현재 페이지의 행 객체**이고
+     * `selectedIds` 는 페이지를 가로지르는 **누적 식별자**다. 서버 페이징에서 둘의 길이가
+     * 다른 것이 정상이며, 그 차이를 감출 방법은 없다 — 컴포넌트가 다른 페이지의 행을
+     * 갖고 있지 않기 때문이다.
+     */
     private _fireSelectionChange;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -90,6 +158,7 @@ export declare class URichTable extends LitElement {
     private _handleCopy;
     private _handlePaste;
     private _moveFocus;
+    /** `Ctrl`/`Cmd` + `A` — 전체선택 체크박스와 같은 범위(현재 페이지 합집합)여야 한다. */
     private _selectAll;
     static define(tagName?: string): void;
 }

package/dist/components/u-rich-table/URichTable.js

@@ -102,6 +102,44 @@ var URichTable = class URichTable extends LitElement {
 		this.rowErrors = next;
 	}
 	/**
+	* 선택된 행의 **식별자 집합** — 페이지를 가로질러 누적된 전부.
+	*
+	* `getSelectedRows()` 는 현재 페이지의 행 객체만 돌려주므로(갖고 있지 않은 행을 만들 수 없다)
+	* *"여러 페이지에 걸쳐 고른 뒤 일괄 처리"* 에는 이쪽이 필요하다.
+	*
+	* ⚠**스냅샷이다.** 내부 집합을 그대로 넘기면 `ReadonlySet` 이 타입 수준 약속일 뿐이라
+	* JS 소비자가 `add` 로 내부 상태를 **갱신 신호 없이** 망가뜨릴 수 있다. 복제 비용은
+	* 선택 크기에 비례하고 무시할 수준이다.
+	*/
+	get selectedRowIds() {
+		return new Set(this.selectedIds);
+	}
+	/**
+	* 선택을 **통째로 대체**한다 — 페이지를 가로지르는 누적분까지.
+	*
+	* 앱이 자기 상태를 정본으로 삼는 경우(외부 저장·복원, 필터 변경 시 정리)의 진입점이다.
+	* 현재 페이지에 없는 식별자를 넣어도 된다 — 그 페이지로 이동하면 선택된 것으로 렌더된다.
+	*
+	* ⚠**같은 집합이면 아무 일도 하지 않는다.** 앱이 `selection-change` 를 받아 자기 상태를
+	* 갱신하고 다시 이것을 부르는 것이 자연스러운 배선인데, 무조건 발생시키면 그 자리가
+	* **무한 루프**가 된다.
+	*/
+	setSelection(ids) {
+		const next = new Set(ids);
+		if (next.size === this.selectedIds.size && [...next].every((id) => this.selectedIds.has(id))) return;
+		this.selectedIds = next;
+		this._fireSelectionChange();
+	}
+	/**
+	* 선택을 **전부** 비운다 — 페이지를 가로지르는 누적분까지.
+	*
+	* 전체선택 체크박스는 «이 페이지»만 다루므로 전역 소거의 자리가 없다. 일괄 처리를 끝낸 뒤
+	* 앱이 상태를 되돌리는 경로가 여기다. `selection-change` 를 발생시킨다.
+	*/
+	clearSelection() {
+		this.setSelection([]);
+	}
+	/**
 	* 행의 식별자. 선택·확장·행 오류 상태가 전부 이 값으로 추적된다.
 	*
 	* ⚠`_id` 는 이 컴포넌트가 **부여하지 않는다.** 소비자가 넣어 주지 않으면 모든 행의
@@ -121,9 +159,22 @@ var URichTable = class URichTable extends LitElement {
 		this._warnedMissingRowId = true;
 		console.warn("[@iyulab/data-components] u-rich-table: rows have no `_id`, so selection is tracked by **position**. Re-sorting or re-paging the data moves the selection to a different row. Give every row a unique `_id`.");
 	}
+	/**
+	* **현재 페이지의** 선택된 행. 서버 페이징에서 다른 페이지의 선택분은 여기 없다 —
+	* 이 컴포넌트가 갖고 있지 않은 행을 돌려줄 수는 없기 때문이다.
+	* 페이지를 가로지르는 선택 집합이 필요하면 {@link selectedRowIds} 를 쓴다.
+	*/
 	getSelectedRows() {
 		return this.data.filter((row, i) => this.selectedIds.has(this._rowId(row, i)));
 	}
+	/** 이 페이지 행들의 식별자. 전체선택/해제가 «이 페이지» 범위임을 정의하는 값이다. */
+	_pageRowIds() {
+		return this.data.map((row, i) => this._rowId(row, i));
+	}
+	/** 현재 페이지에서 선택된 행 수 — 전체선택 체크박스의 «분자». */
+	get _selectedOnPage() {
+		return this._pageRowIds().reduce((n, id) => n + (this.selectedIds.has(id) ? 1 : 0), 0);
+	}
 	render() {
 		return html`
       ${this._renderToolbar()}
@@ -138,19 +189,31 @@ var URichTable = class URichTable extends LitElement {
       ${this._renderPagination()}
     `;
 	}
+	/**
+	* ⚠**두 숫자를 섞지 않는다.** 체크박스는 «이 페이지»를 켜고 끄므로 그 상태도 페이지 기준이고,
+	* 라벨의 건수는 페이지를 가로지르는 **누적**이다. 종전에는 분자만 누적이고 분모가 페이지라
+	* 다른 페이지의 선택분이 이 페이지의 체크 상태로 새어 나왔다 — 페이지 1을 전량 선택하고
+	* 넘어가면 페이지 2에서 아무것도 고르지 않았는데 체크박스가 켜져 보였고, 그것을 끄면
+	* 페이지 1의 선택이 조용히 사라졌다.
+	*/
 	_renderToolbar() {
-		const selectedCount = this.selectedIds.size;
+		const total = this.selectedIds.size;
+		const onPage = this._selectedOnPage;
+		const crossesPages = total > onPage;
 		return html`
       <div class="toolbar">
         ${this.selectable ? html`
           <div class="selection-info">
             <input type="checkbox"
-              .checked=${selectedCount > 0 && selectedCount === this.data.length}
-              .indeterminate=${selectedCount > 0 && selectedCount < this.data.length}
+              .checked=${this.data.length > 0 && onPage === this.data.length}
+              .indeterminate=${onPage > 0 && onPage < this.data.length}
               @change=${this._onSelectAll} />
-            ${selectedCount > 0 ? html`<span>${selectedCount}건 선택됨</span>` : ""}
+            ${total > 0 ? html`<span>${crossesPages ? messages.text("selectedAcrossPages", {
+			count: total,
+			onPage
+		}) : messages.text("selected", { count: total })}</span>` : ""}
           </div>
-          ${selectedCount > 0 ? html`<slot name="bulk-actions"></slot>` : ""}
+          ${total > 0 ? html`<slot name="bulk-actions"></slot>` : ""}
         ` : ""}
         <div style="flex:1"></div>
         <slot name="toolbar-end"></slot>
@@ -332,16 +395,45 @@ var URichTable = class URichTable extends LitElement {
 			25,
 			50,
 			100
-		].map((s) => html`<option value=${s} ?selected=${s === this.pageSize}>${s}행</option>`)}
+		].map((s) => html`<option value=${s} ?selected=${s === this.pageSize}>${messages.text("rowsPerPage", { size: s })}</option>`)}
           </select>
         </div>
       </div>
     `;
 	}
+	/**
+	* 전체선택 체크박스 — 범위는 **현재 페이지**다(합집합/차집합, 치환이 아니다).
+	* 종전에는 켤 때 `new Set(현재 페이지)` 로 **치환**하고 끌 때 `new Set()` 으로 **전역 소거**해서,
+	* 어느 쪽이든 다른 페이지의 선택분이 함께 날아갔다. 전역 소거가 필요하면 {@link clearSelection}.
+	*
+	* ## 왜 `select-all` 을 따로 내보내는가
+	*
+	* `selection-change` 만으로는 *"사용자가 세 행을 골랐다"* 와 *"사용자가 전체선택을 눌렀다"* 가
+	* 구분되지 않는다. 서버 페이징에서 그 구분은 앱에 필요하다 — 전체선택을 누른 순간이
+	* *"이 조건에 맞는 N건 전부"* 를 제안할 자리이기 때문이다.
+	*
+	* ⚠**`scope: 'page' | 'all'` 필드는 두지 않았다.** 이 컴포넌트는 `'all'` 을 **낼 수 없다** —
+	* 다른 페이지의 행을 갖고 있지 않고, 서버 페이징에서 «전역 전체선택»은 id 목록이 아니라
+	* **조회 조건**이라 컴포넌트가 표현할 수 있는 것이 아니다. 값이 하나뿐인 유니온은
+	* *"라이브러리가 모르는 개념을 아는 척하는"* 필드가 된다. ⇒ 컴포넌트는 **의도만** 알리고
+	* 전역 해석은 앱이 한다.
+	*/
 	_onSelectAll(e) {
-		if (e.target.checked) this.selectedIds = new Set(this.data.map((r, i) => this._rowId(r, i)));
-		else this.selectedIds = /* @__PURE__ */ new Set();
+		const checked = e.target.checked;
+		const pageIds = this._pageRowIds();
+		const next = new Set(this.selectedIds);
+		for (const id of pageIds) if (checked) next.add(id);
+		else next.delete(id);
+		this.selectedIds = next;
 		this._fireSelectionChange();
+		this.dispatchEvent(new CustomEvent("select-all", {
+			detail: {
+				checked,
+				pageRowIds: pageIds
+			},
+			bubbles: true,
+			composed: true
+		}));
 	}
 	_onRowSelect(rowId) {
 		const next = new Set(this.selectedIds);
@@ -578,9 +670,18 @@ var URichTable = class URichTable extends LitElement {
 		const value = this.data[rowIndex]?.[this.columns[colIndex]?.key];
 		this._onCellDblClick(rowIndex, colIndex, value);
 	}
+	/**
+	* ⚠**두 필드가 서로 다른 것을 센다.** `selectedRows` 는 **현재 페이지의 행 객체**이고
+	* `selectedIds` 는 페이지를 가로지르는 **누적 식별자**다. 서버 페이징에서 둘의 길이가
+	* 다른 것이 정상이며, 그 차이를 감출 방법은 없다 — 컴포넌트가 다른 페이지의 행을
+	* 갖고 있지 않기 때문이다.
+	*/
 	_fireSelectionChange() {
 		this.dispatchEvent(new CustomEvent("selection-change", {
-			detail: { selectedRows: this.getSelectedRows() },
+			detail: {
+				selectedRows: this.getSelectedRows(),
+				selectedIds: [...this.selectedIds]
+			},
 			bubbles: true,
 			composed: true
 		}));
@@ -620,8 +721,11 @@ var URichTable = class URichTable extends LitElement {
 			colIndex: newCol
 		};
 	}
+	/** `Ctrl`/`Cmd` + `A` — 전체선택 체크박스와 같은 범위(현재 페이지 합집합)여야 한다. */
 	_selectAll() {
-		this.selectedIds = new Set(this.data.map((r, i) => this._rowId(r, i)));
+		const next = new Set(this.selectedIds);
+		for (const id of this._pageRowIds()) next.add(id);
+		this.selectedIds = next;
 		this._fireSelectionChange();
 	}
 	static define(tagName = "u-rich-table") {

package/dist/components/u-rich-table/types.d.ts

@@ -31,8 +31,24 @@ export interface FilterState {
     [field: string]: string;
 }
 export interface RichTableEventMap {
+    /**
+     * ⚠두 필드가 서로 다른 것을 센다 — `selectedRows` 는 **현재 페이지의 행 객체**,
+     * `selectedIds` 는 페이지를 가로지르는 **누적 식별자**다. 서버 페이징에서 길이가 다른 것이 정상이다.
+     */
     'selection-change': CustomEvent<{
         selectedRows: Record<string, unknown>[];
+        selectedIds: string[];
+    }>;
+    /**
+     * 사용자가 **전체선택 체크박스**를 조작했다. `selection-change` 와 함께 발생한다.
+     *
+     * 이 이벤트가 따로 있는 이유는 *"세 행을 골랐다"* 와 *"전체선택을 눌렀다"* 를 가르기 위해서다 —
+     * 서버 페이징에서 후자는 앱이 *"조건에 맞는 전체 N건"* 을 제안할 자리다.
+     * `pageRowIds` 는 이번 조작이 더하거나 뺀 **현재 페이지의** 식별자다.
+     */
+    'select-all': CustomEvent<{
+        checked: boolean;
+        pageRowIds: string[];
     }>;
     'row-create': CustomEvent<{
         row: Record<string, unknown>;

package/dist/index.d.ts

@@ -1,3 +1,15 @@
 export * from './components/data-view/UDataView';
 export * from './components/simple-sheet/USimpleSheet';
 export * from './components/u-rich-table/URichTable';
+/**
+ * `URichTable` 의 공개 API 가 요구하는 타입.
+ *
+ * ⚠**이 줄이 없으면 «타입이 있는데 쓸 수 없는 컴포넌트»가 된다** — `columns` 는
+ * `ColumnDef[]` 를 요구하는데 소비자는 그 이름을 루트에서 import 할 수 없어, 내부 경로를
+ * 딥임포트하거나(내부 배치가 곧 공개 계약이 된다) 같은 모양을 손으로 복제해야 했다
+ * (업스트림이 필드를 바꿔도 모른 채 조용히 갈라진다).
+ *
+ * ★다른 두 컴포넌트는 타입이 **같은 파일**에 있어 위 `export *` 로 이미 나간다 —
+ * `URichTable` 만 타입을 `types.ts` 로 분리해 배럴이 지나치고 있었다.
+ */
+export type { ColumnDef, CellPosition, SortState, FilterState, RichTableEventMap, } from './components/u-rich-table/types';

package/dist/react.d.ts

@@ -2,7 +2,6 @@ import { EventName } from '@lit/react';
 import { USimpleSheet } from './components/simple-sheet/USimpleSheet';
 import { UDataView } from './components/data-view/UDataView';
 import { URichTable } from './components/u-rich-table/URichTable';
-import { RichTableEventMap } from './components/u-rich-table/types';
 /** USimpleSheet React 래퍼 — `change` 이벤트는 `onChange`로 노출 */
 export declare const USimpleSheetReact: import('@lit/react').ReactWebComponent<USimpleSheet, {
     onChange: EventName<CustomEvent<{
@@ -13,15 +12,44 @@ export declare const USimpleSheetReact: import('@lit/react').ReactWebComponent<U
 export declare const UDataViewReact: import('@lit/react').ReactWebComponent<UDataView, {}>;
 /** URichTable React 래퍼 — RichTableEventMap의 모든 이벤트를 onXxx로 노출 */
 export declare const URichTableReact: import('@lit/react').ReactWebComponent<URichTable, {
-    onSelectionChange: EventName<RichTableEventMap["selection-change"]>;
-    onRowCreate: EventName<RichTableEventMap["row-create"]>;
-    onRowUpdate: EventName<RichTableEventMap["row-update"]>;
-    onRowDelete: EventName<RichTableEventMap["row-delete"]>;
-    onRowExpand: EventName<RichTableEventMap["row-expand"]>;
-    onSortChange: EventName<RichTableEventMap["sort-change"]>;
-    onFilterChange: EventName<RichTableEventMap["filter-change"]>;
-    onPageChange: EventName<RichTableEventMap["page-change"]>;
-    onPaste: EventName<RichTableEventMap["paste"]>;
+    readonly onSelectionChange: EventName<CustomEvent<{
+        selectedRows: Record<string, unknown>[];
+        selectedIds: string[];
+    }>>;
+    readonly onSelectAll: EventName<CustomEvent<{
+        checked: boolean;
+        pageRowIds: string[];
+    }>>;
+    readonly onRowCreate: EventName<CustomEvent<{
+        row: Record<string, unknown>;
+    }>>;
+    readonly onRowUpdate: EventName<CustomEvent<{
+        row: Record<string, unknown>;
+        field: string;
+        value: unknown;
+        oldValue: unknown;
+    }>>;
+    readonly onRowDelete: EventName<CustomEvent<{
+        row: Record<string, unknown>;
+    }>>;
+    readonly onRowExpand: EventName<CustomEvent<{
+        row: Record<string, unknown>;
+        expanded: boolean;
+    }>>;
+    readonly onSortChange: EventName<CustomEvent<{
+        field: string;
+        direction: "asc" | "desc" | null;
+    }>>;
+    readonly onFilterChange: EventName<CustomEvent<{
+        filters: import('.').FilterState;
+    }>>;
+    readonly onPageChange: EventName<CustomEvent<{
+        page: number;
+        pageSize: number;
+    }>>;
+    readonly onPaste: EventName<CustomEvent<{
+        rows: Record<string, unknown>[];
+    }>>;
 }>;
 export { USimpleSheet, UDataView, URichTable };
 export type { SheetColumn } from './components/simple-sheet/USimpleSheet';

package/dist/react.js

@@ -34,6 +34,7 @@ var URichTableReact = createComponent({
 	react: React,
 	events: {
 		onSelectionChange: "selection-change",
+		onSelectAll: "select-all",
 		onRowCreate: "row-create",
 		onRowUpdate: "row-update",
 		onRowDelete: "row-delete",

package/dist/utilities/messages.d.ts

@@ -21,5 +21,5 @@
  * 딸려 온다**(`Locale.getValue('valueMissing')`). 같은 문장을 이 표에 복제하면 두 곳이
  * 갈라진다.
  */
-export type DataMessageKey = 'empty' | 'loading' | 'filterPlaceholder' | 'filterAll' | 'addRow' | 'pageInfo' | 'noMatch';
+export type DataMessageKey = 'empty' | 'loading' | 'filterPlaceholder' | 'filterAll' | 'addRow' | 'pageInfo' | 'noMatch' | 'selected' | 'selectedAcrossPages' | 'rowsPerPage';
 export declare const messages: import('@iyulab/components/dist/utilities/Locale.js').LocaleNamespace<DataMessageKey>;

package/dist/utilities/messages.js

@@ -8,7 +8,10 @@ messages.register("en", {
 	filterAll: "All",
 	addRow: "+ New row",
 	pageInfo: "Showing {start}-{end} of {total}",
-	noMatch: "No matching item"
+	noMatch: "No matching item",
+	selected: "{count} selected",
+	selectedAcrossPages: "{count} selected ({onPage} on this page)",
+	rowsPerPage: "{size} rows"
 });
 messages.register("ko", {
 	empty: "데이터가 없습니다",
@@ -17,7 +20,10 @@ messages.register("ko", {
 	filterAll: "전체",
 	addRow: "+ 새 행",
 	pageInfo: "전체 {total}건 중 {start}-{end} 표시",
-	noMatch: "일치하는 항목 없음"
+	noMatch: "일치하는 항목 없음",
+	selected: "{count}건 선택됨",
+	selectedAcrossPages: "{count}건 선택됨 (이 페이지 {onPage}건)",
+	rowsPerPage: "{size}행"
 });
 //#endregion
 export { messages };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/data-components",
   "description": "iyulab data visualization components",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "keywords": [
     "iyulab",
     "web-components",
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
@@ -22,6 +23,9 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -51,11 +55,12 @@
   ],
   "scripts": {
     "start": "vite",
-    "build": "eslint && vite build",
+    "build": "npm run typecheck && eslint && vite build",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix"
+    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@iyulab/components": "^1.23.0",

package/skills/iyulab-data-components/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: iyulab-data-components
+description: Data-oriented web components built on Lit — a server-paged rich table with inline editing and cross-page selection, a spreadsheet-like grid, and a multi-layout data viewer. Use when working with @iyulab/data-components package.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.13.0"
+---
+
+# @iyulab/data-components
+
+Three custom elements for displaying and editing tabular data. Built on
+[Lit](https://lit.dev/); usable from any framework or plain HTML.
+
+## Install
+
+```bash
+npm install @iyulab/data-components
+```
+
+## Which component do I use?
+
+| Tag | Use it when | Reference |
+|---|---|---|
+| `u-rich-table` | The rows come from a **server** — paging, sorting and filtering are the app's job, and you need selection, inline editing or expandable detail rows | [rich-table.md](references/components/rich-table.md) |
+| `u-simple-sheet` | The data is a **free-form grid** of cells the user types into, spreadsheet-style (fill handle, ranges, clipboard) | [simple-sheet.md](references/components/simple-sheet.md) |
+| `u-data-view` | You are **displaying** records and want to switch between grid / list / table layouts without rebuilding markup | [data-view.md](references/components/data-view.md) |
+
+`u-rich-table` and `u-simple-sheet` overlap only superficially. The table is
+**record-oriented** (a row is an object with named columns, and the app owns the
+query); the sheet is **cell-oriented** (a row is an array of strings, and the
+component owns the grid).
+
+## Importing
+
+Import the barrel to register every element:
+
+```ts
+import '@iyulab/data-components';
+```
+
+…or import one element to keep the bundle small:
+
+```ts
+import '@iyulab/data-components/dist/components/u-rich-table/URichTable.js';
+```
+
+Registration is a **module side effect** (`@customElement`), so the import must
+not be elided — do not mark this package as side-effect-free in a bundler
+config, or the elements silently never register.
+
+## Types
+
+Every type the public API asks for is exported from the package root:
+
+```ts
+import type {
+  ColumnDef, CellPosition, SortState, FilterState, RichTableEventMap,
+} from '@iyulab/data-components';
+```
+
+Do **not** deep-import from `dist/components/...` for types. The subpath exists,
+but it turns the internal layout into a contract you depend on.
+
+## Theming
+
+Colors come from the `@iyulab/components` design tokens (`--u-*`) and follow the
+active theme automatically. Per-component knobs are listed in each reference
+document under *CSS Custom Properties*.

package/skills/iyulab-data-components/references/components/data-view.md

@@ -0,0 +1,63 @@
+# u-data-view
+
+```ts
+import '@iyulab/data-components/dist/components/data-view/UDataView.js';
+```
+
+**Tag:** `u-data-view`
+
+Read-only viewer that renders the same records as a card **grid**, a **list**, or
+a **table**, without the app rebuilding markup per layout.
+
+```html
+<u-data-view mode="list"></u-data-view>
+```
+
+```ts
+const view = document.querySelector('u-data-view')!;
+view.items = records;
+view.columns = [           // used by mode="table"; inferred from the first item when omitted
+  { key: 'name',  label: 'Name' },
+  { key: 'owner', label: 'Owner', width: '160px' },
+];
+```
+
+A toolbar above the content shows the item count and one button per layout;
+clicking a button sets `mode`. `mode` is also a plain property, so the app can
+set it directly and persist the user's choice.
+
+Switching layout is a **local** interaction — the component does not emit an
+event for it. Read `view.mode` when you need the current layout.
+
+Cell and card rendering can be replaced without giving up the layout logic:
+
+```ts
+view.renderCard = (item, index) => html`<strong>${item.name}</strong>`;
+view.renderCell = (item, column) => column.key === 'size' ? formatBytes(item.size) : item[column.key];
+```
+
+## Display only
+
+`u-data-view` renders records; it does not select, sort, page or emit events.
+When the user needs to act on rows — selection, inline edit, server paging — use
+[`u-rich-table`](./rich-table.md).
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `items` | `DataItem[]` | `[]` | | Records to display. `DataItem` is `Record<string, any>` — the component deliberately does not constrain the app's domain type |
+| `mode` | `'grid'\|'list'\|'table'` | `'grid'` | | Current layout |
+| `columns` | `DataColumn[]` | — | | Columns for `mode="table"`; inferred from the first item when omitted |
+| `gridMinWidth` | `string` | `'200px'` | | Minimum card width in `mode="grid"` (CSS length) |
+| `gap` | `string` | `'1rem'` | | Gap between cards or rows (CSS length) |
+| `renderCard` | `(item, index) => TemplateResult` | — | | Replaces card content in `grid` / `list` |
+| `renderCell` | `(item, column, index) => TemplateResult \| string` | — | | Replaces cell content in `table` |
+
+## DataColumn
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | `string` | Property read from the item |
+| `label` | `string` | Header text (defaults to `key`) |
+| `width` | `string` | CSS width |

package/skills/iyulab-data-components/references/components/rich-table.md

@@ -0,0 +1,209 @@
+# u-rich-table
+
+```ts
+import '@iyulab/data-components/dist/components/u-rich-table/URichTable.js';
+```
+
+**Tag:** `u-rich-table`
+
+Record-oriented table for **server-paged** data: selection that survives paging,
+inline editing with validation, column filters, expandable detail rows and
+TSV clipboard paste.
+
+```html
+<u-rich-table selectable editable filterable></u-rich-table>
+```
+
+```ts
+const table = document.querySelector('u-rich-table')!;
+table.columns = [
+  { key: 'name',  label: 'Name',  sortable: true, editable: true, required: true },
+  { key: 'state', label: 'State', type: 'badge', badgeColors: { open: 'green' } },
+];
+table.data = rows;          // the CURRENT page only
+table.totalCount = 1240;    // the total the query matches
+table.currentPage = 1;
+table.pageSize = 25;
+```
+
+---
+
+## Read this first: give every row an `_id`
+
+The component does **not** assign row identity. Selection, expansion and row
+errors are all tracked by `row._id`.
+
+```ts
+table.data = rows.map(r => ({ ...r, _id: r.documentNo }));
+```
+
+If `_id` is missing, every row's identity is `undefined`, a `Set` holds exactly
+one of those — so **selecting one row appears to select all of them**. The
+component falls back to the row's *position* and warns once on the console, but
+position-based identity moves the selection to a different row as soon as the
+data is re-sorted or re-paged.
+
+## Read this second: the app owns the query
+
+`u-rich-table` never fetches, sorts, filters or slices. It renders the page you
+give it and tells you what the user asked for:
+
+```ts
+table.addEventListener('page-change',   e => load({ page: e.detail.page, size: e.detail.pageSize }));
+table.addEventListener('sort-change',   e => load({ sort: e.detail.field, dir: e.detail.direction }));
+table.addEventListener('filter-change', e => load({ filters: e.detail.filters }));
+```
+
+`totalCount` is what the pager counts — not `data.length`. Setting `data` alone
+produces a table that believes it holds every matching record.
+
+## Selection across pages
+
+Two facts are deliberately separate, because in server paging they differ:
+
+| What you want | Where to read it |
+|---|---|
+| The selected **row objects on this page** | `getSelectedRows()` / `event.detail.selectedRows` |
+| Every selected **identifier**, across all pages visited | `selectedRowIds` / `event.detail.selectedIds` |
+
+The component cannot return row objects it was never given, so a bulk action
+spanning pages must work from the identifiers:
+
+```ts
+table.addEventListener('selection-change', e => {
+  bulkBar.count = e.detail.selectedIds.length;   // accumulated
+  preview.rows  = e.detail.selectedRows;         // this page
+});
+
+await deleteAll([...table.selectedRowIds]);
+table.clearSelection();
+```
+
+The header checkbox is scoped to the **current page** — that is what makes it
+truthful when the other pages are not loaded. `select-all` fires alongside
+`selection-change` so the app can distinguish *"the user ticked three rows"*
+from *"the user asked for everything"* and offer a "select all N matching"
+affordance of its own:
+
+```ts
+table.addEventListener('select-all', e => {
+  offerSelectEntireQuery.hidden = !e.detail.checked;   // e.detail.pageRowIds = this page's ids
+});
+```
+
+`setSelection(ids)` replaces the accumulated set (identifiers not on the current
+page are allowed). It is a no-op when the set is unchanged — without that, the
+natural wiring of *listen to `selection-change` → store → write back* would loop
+forever.
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `columns` | `ColumnDef[]` | `[]` | | Column definitions — see *ColumnDef* below |
+| `data` | `Record<string, unknown>[]` | `[]` | | Rows of the **current page**. Give each a unique `_id` |
+| `totalCount` | `number` | `0` | | Total rows the query matches, across all pages |
+| `pageSize` | `number` | `25` | | Rows per page |
+| `currentPage` | `number` | `1` | | 1-based page number |
+| `loading` | `boolean` | `false` | | Shows the loading message instead of rows |
+| `emptyMessage` | `string` | `''` | | Text shown when there are no rows (falls back to the locale string) |
+| `loadingMessage` | `string` | `''` | | Text shown while `loading` |
+| `filterPlaceholder` | `string` | `''` | | Placeholder of the column filter inputs |
+| `filterAllLabel` | `string` | `''` | | Label of the "all" option in `select` filters |
+| `addRowLabel` | `string` | `''` | | Label of the add-row button |
+| `pageInfoFormatter` | `(total, start, end) => string` | locale string | | Builds the pager caption. A function rather than a template, because word order differs per language |
+| `selectable` | `boolean` | `false` | | Renders the selection column |
+| `editable` | `boolean` | `false` | | Enables inline cell editing on columns marked `editable` |
+| `addable` | `boolean` | `false` | | Renders the add-row control |
+| `filterable` | `boolean` | `false` | | Renders the filter row for columns marked `filterable` |
+| `expandable` | `boolean` | `false` | | Renders the expander column; pair with `detailRenderer` |
+| `detailRenderer` | `(row) => TemplateResult` | — | | Renders the expanded detail row |
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `getSelectedRows(): Record<string, unknown>[]` | Selected rows **on the current page** |
+| `setSelection(ids: Iterable<string>): void` | Replace the accumulated selection; no-op if unchanged |
+| `clearSelection(): void` | Clear it entirely, across pages |
+| `setRowError(rowId, message): void` | Mark a row as failed (e.g. the server rejected a save) |
+| `clearRowError(rowId): void` | Remove that mark |
+
+## Getters
+
+| Getter | Description |
+|---|---|
+| `selectedRowIds: ReadonlySet<string>` | Snapshot of every selected identifier, across pages |
+
+## Events
+
+All events bubble and cross shadow boundaries. `RichTableEventMap` types every
+`detail`:
+
+```ts
+import type { RichTableEventMap } from '@iyulab/data-components';
+type SelectionChange = RichTableEventMap['selection-change'];
+```
+
+| Event | `detail` | Fired when |
+|---|---|---|
+| `selection-change` | `{ selectedRows, selectedIds }` | Selection changed by any route |
+| `select-all` | `{ checked, pageRowIds }` | The header checkbox was toggled |
+| `sort-change` | `{ field, direction }` | A sortable header was clicked (`direction` is `null` when cleared) |
+| `filter-change` | `{ filters }` | A column filter changed |
+| `page-change` | `{ page, pageSize }` | The pager or page-size selector moved |
+| `row-update` | `{ row, field, value, oldValue }` | An inline edit was committed |
+| `row-create` | `{ row }` | The add-row control produced a row |
+| `row-delete` | `{ row }` | A row was deleted |
+| `row-expand` | `{ row, expanded }` | A detail row was opened or closed |
+| `paste` | `{ rows }` | TSV was pasted into the grid |
+
+## ColumnDef
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | `string` | Property read from the row object |
+| `label` | `string` | Header text |
+| `width` | `string` | CSS width |
+| `type` | `'text'\|'number'\|'date'\|'select'\|'badge'` | Cell renderer and editor |
+| `options` | `{ value, label }[]` | Choices for `type: 'select'` |
+| `badgeColors` | `Record<string, string>` | Value → color for `type: 'badge'` |
+| `align` | `'left'\|'center'\|'right'` | Cell alignment |
+| `sortable` | `boolean` | Header emits `sort-change` |
+| `editable` | `boolean` | Cell is editable when the table is `editable` |
+| `required` | `boolean` | Empty value fails validation |
+| `filterable` | `boolean` | Column appears in the filter row |
+| `filterType` | `'text'\|'select'` | Filter control |
+| `validator` | `(value, row) => string \| null` | Returns an error message, or `null` when valid |
+| `render` | `(value, row) => string \| HTMLElement` | Custom cell rendering |
+| `clipboardParse` | `(text) => unknown` | Parses a pasted cell |
+| `clipboardFormat` | `(value) => string` | Formats a copied cell |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `bulk-actions` | Toolbar area shown while rows are selected |
+| `toolbar-end` | Trailing toolbar area, always shown |
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Arrow keys | Move the focused cell |
+| `Enter` | Start editing the focused cell / commit and move down |
+| `Escape` | Cancel editing |
+| `Tab` | Commit and move to the next cell |
+| `Space` | Toggle selection of the focused row (when `selectable`) |
+| `Delete` | Emit `row-delete` for every selected row |
+| `Ctrl`/`Cmd` + `A` | Select every row **on this page** — same scope as the header checkbox |
+| `Ctrl`/`Cmd` + `C` | Copy the selection as TSV |
+| `Ctrl`/`Cmd` + `V` | Paste TSV (emits `paste`) |
+
+## Localization
+
+`emptyMessage`, `loadingMessage`, `filterPlaceholder`, `filterAllLabel` and
+`addRowLabel` default to `''` and fall back to the package's locale strings —
+set them only to override the translation for a specific table.

package/skills/iyulab-data-components/references/components/simple-sheet.md

@@ -0,0 +1,107 @@
+# u-simple-sheet
+
+```ts
+import '@iyulab/data-components/dist/components/simple-sheet/USimpleSheet.js';
+```
+
+**Tag:** `u-simple-sheet`
+
+Spreadsheet-like grid of text cells: range selection, fill handle, clipboard
+copy/paste, per-column dropdowns, computed columns, display formatting,
+resizable columns and undo/redo history.
+
+```html
+<u-simple-sheet rows="30" cols="6"></u-simple-sheet>
+```
+
+```ts
+const sheet = document.querySelector('u-simple-sheet')!;
+sheet.columns = [
+  { key: 'item',  label: 'Item',  width: 180 },
+  { key: 'qty',   label: 'Qty',   format: { maximumFractionDigits: 0 } },
+  { key: 'price', label: 'Price', format: { style: 'currency', currency: 'USD' } },
+  { key: 'total', label: 'Total', compute: (row, data) => String(+data[row][1] * +data[row][2]) },
+  { key: 'state', label: 'State', options: ['draft', 'sent'], strict: true },
+];
+sheet.addEventListener('change', e => save(sheet.getDataAsObjects()));
+```
+
+The data is a **2-D array of strings** — the sheet stores what the user typed and
+never coerces it. `format` changes only what is displayed; `getData()` returns
+the raw values.
+
+## Cell-oriented, not record-oriented
+
+Use `u-simple-sheet` when the grid itself is the input surface (an estimate, a
+bulk-entry form, a paste target). When rows are records fetched page by page
+from a server, use [`u-rich-table`](./rich-table.md) instead.
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `data` | `string[][]` | `[]` | | Initial cell values, row-major |
+| `columns` | `SheetColumn[]` | — | | Column definitions; omit for generic `A`, `B`, `C`… columns |
+| `rows` | `number` | `20` | | Row count when `data` is shorter |
+| `cols` | `number` | `10` | | Column count when neither `data` nor `columns` says otherwise |
+| `readonly` | `boolean` | `false` | | Blocks editing, paste and fill |
+| `noMatchMessage` | `string` | `''` | | Text shown when a `strict` dropdown has no match (falls back to the locale string) |
+| `theme` | `'light'\|'dark'` | — | ✓ | Forces a theme. Unset follows the ancestor `theme`/`data-theme` context (`:host-context`, Chromium only) |
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `getData(): string[][]` | Current values as a copied 2-D array |
+| `getDataAsObjects(): Record<string, string>[]` | Rows keyed by `SheetColumn.key` (or `A`, `B`, `C`… when `columns` is unset) |
+| `setData(data: string[][]): void` | Replace all values and re-render |
+| `setCell(row, col, value): void` | Set one cell — recomputes, pushes history and emits `change` |
+| `getSelection(): { minRow, maxRow, minCol, maxCol } \| null` | Current range, normalized |
+| `setSelection(range): void` | Select a range programmatically (clamped to the grid) |
+| `selectAll(): void` | Select every cell |
+
+## Getters
+
+| Getter | Description |
+|---|---|
+| `canUndo: boolean` | History has an earlier state |
+| `canRedo: boolean` | History has a later state |
+
+## Events
+
+| Event | `detail` | Fired when |
+|---|---|---|
+| `change` | `{ data: string[][] }` | Any edit, paste, fill or `setCell()` committed a value |
+
+## SheetColumn
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | `string` | Object key used by `getDataAsObjects()` |
+| `label` | `string` | Header text |
+| `width` | `number` | Column width in px |
+| `readonly` | `boolean` | Column cannot be edited |
+| `options` | `string[] \| ((row, col) => string[])` | Dropdown choices, static or per cell |
+| `strict` | `boolean` | Only listed options may be entered (default: free text) |
+| `compute` | `(rowIndex, data) => string` | Derived value. Makes the column read-only; evaluated left→right, top→bottom |
+| `format` | `Intl.NumberFormatOptions \| ((value, rowIndex) => string)` | Display formatting only — the stored value is untouched |
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Arrow keys | Move the active cell |
+| `Shift` + arrows | Extend the selection |
+| `Home` / `End` | Jump to the first / last column |
+| `PageUp` / `PageDown` | Jump a screenful of rows |
+| `Enter` / `F2` | Start editing; `Enter` again commits and moves down |
+| `Escape` | Cancel editing |
+| `Tab` | Commit and move right (`Shift` + `Tab` moves left) |
+| `Delete` / `Backspace` | Clear the selected cells |
+| `Ctrl`/`Cmd` + `C` / `V` | Copy / paste the selection as TSV |
+| `Ctrl`/`Cmd` + `Z` | Undo (`Shift` + `Ctrl`/`Cmd` + `Z` redoes) |
+| `Ctrl`/`Cmd` + `Y` | Redo |
+| `Ctrl`/`Cmd` + `D` / `R` | Fill down / fill right from the selection |
+| `Ctrl`/`Cmd` + `A` | Select every cell |
+
+Cut (`Ctrl`/`Cmd` + `X`) is not handled — copy, then `Delete`.