@iyulab/data-components 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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

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/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

@@ -41,7 +41,7 @@ export declare const URichTableReact: import('@lit/react').ReactWebComponent<URi
         direction: "asc" | "desc" | null;
     }>>;
     readonly onFilterChange: EventName<CustomEvent<{
-        filters: import('./react').FilterState;
+        filters: import('.').FilterState;
     }>>;
     readonly onPageChange: EventName<CustomEvent<{
         page: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/data-components",
   "description": "iyulab data visualization components",
-  "version": "0.12.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",

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`.