@iyulab/data-components 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.18.0] - 2026-08-19
+
+### Added
+
+- **`u-record-picker`** — a form control for picking one record from a remote-searched list.
+  Typing filters an inline dropdown; Enter (with nothing highlighted) or a trailing find button
+  opens a modal lookup dialog (search bar + `u-rich-table`). A single click on a dialog row only
+  previews it — Confirm or a row double-click commits the pick, so a stray click in a long
+  result list can't accidentally close the dialog.
+
+## [0.17.0] - 2026-08-17
+
+### Added
+
+- **`u-simple-sheet` gained a `--dc-sheet-height` custom property**, defaulting to `400px` — the
+  value the host was previously hardcoded to. Every other size axis on this component (row height,
+  cell padding, font size) was already a consumer-adjustable custom property; the host's own height
+  was the one dimension left as a literal, so a consumer embedding the sheet in a constrained layout
+  (a form, a panel with a fixed footer) had no supported way to make it shorter or taller — only an
+  external `height` override that fought the component's own `:host` rule on specificity. Unset,
+  rendering is byte-identical to before. Like the other five tokens on this component, it does not
+  derive from a role-layer token and is set with an element selector (`u-simple-sheet { … }`) rather
+  than `:root`.
+
+  This token sets an upper bound, not a natural height: `rows` governs the grid's minimum row
+  *capacity*, not how many rows are visible, so lowering `--dc-sheet-height` does not shrink the
+  number of rows rendered — it constrains the box and leaves the existing `overflow-y: auto` to
+  reach the rest.
+
 ## [0.16.0] - 2026-08-16
 
 ### Added

package/README.md

@@ -9,9 +9,14 @@
 - **URichTable** — 정렬/필터/편집/페이지네이션 지원 테이블 (Lit)
 
 > **UDataGrid (DevExtreme)는 v0.4.0에서 제거되었습니다.**
-> OData 서버 사이드 그리드가 필요하면 `@iyulab/flex-table`을 사용하세요.
 > → [마이그레이션 가이드](./docs/migrating-from-datagrid.md)
 
+**`URichTable`과 `@iyulab/flex-table` 중 무엇을 쓸지**는 OData 연동 여부가 아니라 데이터
+규모와 상호작용 축으로 가릅니다 — 둘 다 OData 등 외부 데이터 소스를 소비할 수 있습니다.
+
+- **`URichTable`** — 중소 규모 데이터, 행 단위 CRUD, selection/필터 UX 중심의 목록·상세 화면
+- **`@iyulab/flex-table`** — 대량 데이터, 셀 단위 편집, 엑셀급 상호작용이 필요한 화면
+
 ## Installation
 
 ```bash
@@ -221,6 +226,12 @@ u-rich-table { --dc-icon-color: #B0B0B0; }
 | `--dc-font-size` | `13px`(`var(--u-density, 13px)`) | 본문 셀 · 편집 입력 · 드롭다운 항목 |
 | `--dc-header-font-size` | `12px` | 열 머리 — `--u-density` 와 무관(본문과 독립) |
 | `--dc-header-font-weight` | `600` | 〃 |
+| `--dc-sheet-height` | `400px` | `:host` 전체 높이 (0.17.0~) |
+
+⚠**`--dc-sheet-height` 는 "자연 높이로 준다"가 아니라 "상한을 정한다"입니다.** `rows` 는
+표시 개수가 아니라 데이터 격자의 **최소 용량**이라, 이 값을 낮춰도 `rows` 만큼의 빈 행이
+줄지는 않습니다 — 그 안에서 내장 `overflow-y: auto` 로 스크롤해 접근하십시오. 콘텐츠
+분량에 맞춰 자동으로 줄어드는 옵트인은 별도 스코프입니다.
 
 ⚠**`--dc-font-size` 만 예외입니다 — `@iyulab/components`/`@iyulab/flex-table` 의 밀도
 스위치(`--u-density`)를 폴백 원본으로 갖습니다**(0.15.0~). 조상에 `--u-density` 를 걸면
@@ -245,11 +256,11 @@ u-simple-sheet {
 `30.5px` 를 선언하십시오. (같은 이유로 **빈 행은 데이터 행보다 1.5px 낮습니다** —
 `0.11.0` 이전부터 그랬고, 교정하면 기본 렌더가 바뀌므로 이 릴리스에서는 두었습니다.)
 
-⚠**`0.11.0` 도 조절점만 엽니다** — 선언하지 않으면 종전과 같은 값으로 그려집니다.
+⚠**조절점만 엽니다** — 선언하지 않으면 종전과 같은 값으로 그려집니다.
 `--dc-row-height`·`--dc-cell-padding-block`·`--dc-cell-padding-inline`·
-`--dc-header-font-size`·`--dc-header-font-weight` 다섯은 `u-simple-sheet` 전용입니다
-(`u-data-view`·`u-rich-table` 은 읽지 않습니다). `--dc-font-size` 만 예외입니다 — 바로
-아래 `u-rich-table` 절 참조.
+`--dc-header-font-size`·`--dc-header-font-weight`·`--dc-sheet-height` 여섯은
+`u-simple-sheet` 전용입니다(`u-data-view`·`u-rich-table` 은 읽지 않습니다).
+`--dc-font-size` 만 예외입니다 — 바로 아래 `u-rich-table` 절 참조.
 
 ### 그리드 밀도 조절 (`u-rich-table` · 0.16.0~)
 

package/dist/_virtual/{_@oxc-project_runtime@0.144.0 → _@oxc-project_runtime@0.146.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.144.0 → _@oxc-project_runtime@0.146.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.144.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

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

@@ -1,6 +1,6 @@
 import { styles } from "./UDataView.styles.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorate.js";
 import { html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";

package/dist/components/simple-sheet/USimpleSheet.js

@@ -1,5 +1,5 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorate.js";
 import { messages } from "../../utilities/messages.js";
 import { styles } from "./USimpleSheet.styles.js";
 import { html } from "lit";

package/dist/components/simple-sheet/USimpleSheet.styles.js

@@ -44,9 +44,23 @@ var baseStyles = css`
     --dc-header-font-size:    12px;   /* 열 머리 — --u-density 와 무관(독립 계약 유지) */
     --dc-header-font-weight:   600;   /* 〃 */
 
+    /* ── 소비자 조절점 — 호스트 높이 ──
+       ★위 다섯과 같은 이유로 열렸지만 축이 다르다 — 저것들은 "셀 하나"의 치수이고
+       이것은 "시트 전체(:host)"의 치수다. 종전에는 여기만 리터럴이라, 셀 치수는 전부
+       조절되는데 그 합인 호스트 크기만 조절 불가능한 비대칭이 있었다.
+       ⚠**역할 토큰에서 파생하지 않는다** — --dc-font-size 와 달리 대응하는 --u- 층
+       스위치가 없다(호스트 크기는 밀도 개념이 아니다). 그래서 var() 폴백이 아니라
+       이 리터럴 기본값 자체가 정본이다.
+       ⚠**rows 를 낮춰도 이 값은 안 줄어든다 — 그리고 그것이 의도다.** rows 는 표시
+       개수가 아니라 데이터 격자의 최소 용량이라, 자연 높이로 접으면 빈 행 개수만큼
+       상자가 늘어나는 별개 결함이 생긴다. 이 토큰이 여는 것은 "소비자가 상한을
+       명시하고 그 안에서 overflow-y:auto 로 스크롤"이지 "내용에 맞춰 줄어든다"가
+       아니다 — 후자가 필요하면 별도 옵트인으로 낸다. */
+    --dc-sheet-height:       400px;
+
     display: block;
     width: 100%;
-    height: 400px;
+    height: var(--dc-sheet-height);
   }
 
   .sheet-container {

package/dist/components/u-record-picker/URecordPicker.d.ts

@@ -0,0 +1,80 @@
+import { PropertyValues } from 'lit';
+import { UFormControlElement } from '@iyulab/components/dist/components/UFormControlElement.js';
+import { UPopover } from '@iyulab/components/dist/components/popover/UPopover.js';
+import { UDialog } from '@iyulab/components/dist/components/dialog/UDialog.js';
+import { URichTable } from '../u-rich-table/URichTable.js';
+import { ColumnDef } from '../u-rich-table/types.js';
+import { PickerItem } from './types.js';
+/**
+ * Form control that picks one record from a remote-searched list. Typing filters an inline
+ * dropdown; Enter (with nothing highlighted) or the trailing find button opens a modal lookup
+ * dialog backed by `u-rich-table`.
+ *
+ * @slot header - Extra content above the dialog's search bar.
+ * @slot footer - Replaces the dialog's default Cancel/Confirm buttons.
+ *
+ * @event change - Fired when the selected record changes (bubbles, composed, non-cancelable —
+ *   same contract as `USelect`/`UInput`). Read `.value` (id) and `.selectedItem` (full record)
+ *   from the target.
+ */
+export declare class URecordPicker extends UFormControlElement<string> {
+    static styles: import('lit').CSSResultGroup[];
+    /** Async lookup — shared by the inline dropdown and the dialog's search bar. */
+    search: (query: string) => Promise<PickerItem[]>;
+    /** Column definitions for the lookup dialog's `u-rich-table` (same shape as `u-rich-table`). */
+    columns: ColumnDef[];
+    /** Lookup dialog header title. Defaults to a localized "Select a record". */
+    dialogTitle?: string;
+    /** Placeholder text for the main input. */
+    placeholder?: string;
+    /** Show a clear ("x") button when a value is selected. */
+    clearable: boolean;
+    /** Inline-dropdown search debounce, in ms. */
+    debounce: number;
+    containerEl?: HTMLElement;
+    inputEl?: HTMLInputElement;
+    popoverEl?: UPopover;
+    dialogEl?: UDialog;
+    tableEl?: URichTable;
+    /** Typed text — distinct from `.value` (the committed id). */
+    private query;
+    private items;
+    private loading;
+    private activeIndex;
+    private error;
+    private inlineDebounceTimer?;
+    private inlineSearchSeq;
+    private dialogDebounceTimer?;
+    private dialogSearchSeq;
+    private dialogQuery;
+    private dialogItems;
+    private dialogLoading;
+    private pendingId;
+    private dialogError;
+    private _selectedItem;
+    /** The full record behind `.value`, or `null` before any selection. */
+    get selectedItem(): PickerItem | null;
+    render(): import('lit-html').TemplateResult<1>;
+    private handleInlineInput;
+    private runInlineSearch;
+    private commitInline;
+    private handleInlineKeydown;
+    private openDialog;
+    private handleDialogSearchInput;
+    private runDialogSearch;
+    /** Single click / focused-row Enter on a non-editable cell — preview only, never closes. */
+    private handleRowActivate;
+    private handleRowDblClick;
+    private confirmDialogSelection;
+    private commitFromDialog;
+    private handleDialogHide;
+    private emitChange;
+    protected updated(changedProperties: PropertyValues): void;
+    protected setValidity(): void;
+    reset(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-record-picker': URecordPicker;
+    }
+}

package/dist/components/u-record-picker/URecordPicker.js

@@ -0,0 +1,307 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorate.js";
+import { messages } from "../../utilities/messages.js";
+import "../u-rich-table/URichTable.js";
+import { styles } from "./styles.js";
+import { html } from "lit";
+import { customElement, property, query, state } from "lit/decorators.js";
+import "@iyulab/components/dist/components/icon/UIcon.js";
+import "@iyulab/components/dist/components/button/UButton.js";
+import { Locale } from "@iyulab/components/dist/utilities/Locale.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { live } from "lit/directives/live.js";
+import "@iyulab/components/dist/components/field/UField.js";
+import "@iyulab/components/dist/components/spinner/USpinner.js";
+import "@iyulab/components/dist/components/popover/UPopover.js";
+import "@iyulab/components/dist/components/option/UOption.js";
+import "@iyulab/components/dist/components/dialog/UDialog.js";
+import { UFormControlElement } from "@iyulab/components/dist/components/UFormControlElement.js";
+//#region src/components/u-record-picker/URecordPicker.ts
+var URecordPicker = class URecordPicker extends UFormControlElement {
+	constructor(..._args) {
+		super(..._args);
+		this.columns = [];
+		this.clearable = false;
+		this.debounce = 250;
+		this.query = "";
+		this.items = [];
+		this.loading = false;
+		this.activeIndex = -1;
+		this.error = false;
+		this.inlineSearchSeq = 0;
+		this.dialogSearchSeq = 0;
+		this.dialogQuery = "";
+		this.dialogItems = [];
+		this.dialogLoading = false;
+		this.pendingId = null;
+		this.dialogError = false;
+		this._selectedItem = null;
+		this.handleInlineInput = (e) => {
+			this.query = e.target.value;
+			this.activeIndex = -1;
+			window.clearTimeout(this.inlineDebounceTimer);
+			if (!this.query) {
+				this.inlineSearchSeq++;
+				this.items = [];
+				this.popoverEl?.hide();
+				return;
+			}
+			this.inlineDebounceTimer = window.setTimeout(() => {
+				this.runInlineSearch(this.query);
+			}, this.debounce);
+		};
+		this.handleInlineKeydown = (e) => {
+			if (e.key === "Enter" && this.items.length === 0) {
+				e.preventDefault();
+				this.openDialog();
+				return;
+			}
+			if (this.items.length === 0) return;
+			switch (e.key) {
+				case "ArrowDown":
+					e.preventDefault();
+					this.activeIndex = (this.activeIndex + 1) % this.items.length;
+					break;
+				case "ArrowUp":
+					e.preventDefault();
+					this.activeIndex = (this.activeIndex - 1 + this.items.length) % this.items.length;
+					break;
+				case "Enter":
+					e.preventDefault();
+					if (this.activeIndex >= 0) this.commitInline(this.items[this.activeIndex]);
+					else this.openDialog();
+					break;
+				case "Escape":
+					e.preventDefault();
+					this.items = [];
+					this.popoverEl?.hide();
+			}
+		};
+		this.openDialog = async () => {
+			this.dialogQuery = this.query;
+			this.pendingId = null;
+			this.popoverEl?.hide();
+			await this.dialogEl?.show();
+			this.runDialogSearch(this.dialogQuery);
+		};
+		this.handleDialogSearchInput = (e) => {
+			this.dialogQuery = e.target.value;
+			window.clearTimeout(this.dialogDebounceTimer);
+			this.dialogDebounceTimer = window.setTimeout(() => {
+				this.runDialogSearch(this.dialogQuery);
+			}, this.debounce);
+		};
+		this.handleRowActivate = (e) => {
+			this.pendingId = e.detail.id;
+		};
+		this.handleRowDblClick = (e) => {
+			const tr = e.composedPath().find((node) => node instanceof HTMLElement && node.tagName === "TR");
+			if (!tr) return;
+			const index = Array.from(this.tableEl.shadowRoot.querySelectorAll("tbody tr")).indexOf(tr);
+			const item = this.dialogItems[index];
+			if (item) this.commitFromDialog(item);
+		};
+		this.confirmDialogSelection = () => {
+			const item = this.dialogItems.find((i) => i.id === this.pendingId);
+			if (item) this.commitFromDialog(item);
+		};
+		this.handleDialogHide = () => {
+			this.pendingId = null;
+		};
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	/** The full record behind `.value`, or `null` before any selection. */
+	get selectedItem() {
+		return this._selectedItem;
+	}
+	render() {
+		return html`
+      <u-field part="field"
+        ?required=${this.required}
+        ?disabled=${this.disabled}
+        ?invalid=${this.invalid}
+        .label=${this.label}
+        .description=${this.description}
+        .validationMessage=${this.validationMessage}
+      >
+        <div class="container" part="container">
+          <input class="main-input" type="text"
+            aria-label=${ifDefined(this.label)}
+            ?disabled=${this.disabled}
+            ?readonly=${this.readonly}
+            placeholder=${ifDefined(this.placeholder)}
+            .value=${live(this.query)}
+            @input=${this.handleInlineInput}
+            @keydown=${this.handleInlineKeydown}
+          />
+          <u-icon class="suffix-item"
+            ?hidden=${!this.clearable || !this.value || this.disabled || this.readonly}
+            lib="internal" name="x"
+          ></u-icon>
+          <u-button class="suffix-item find-btn" variant="ghost"
+            ?disabled=${this.disabled}
+            aria-label=${messages.text("pickerFind")}
+            @click=${this.openDialog}
+          >
+            <u-icon lib="internal" name="search"></u-icon>
+          </u-button>
+        </div>
+      </u-field>
+
+      <u-popover part="popover" role="listbox" for=".container" trigger="manual"
+        strategy="fixed" placement="bottom-start" offset="1"
+      >
+        ${this.loading ? html`<div class="popover-loading"><u-spinner></u-spinner></div>` : this.error ? html`<div class="no-results">${messages.text("pickerSearchError")}</div>` : this.items.length === 0 ? html`<div class="no-results">${messages.text("noMatch")}</div>` : this.items.map((item, i) => html`
+                <u-option .value=${item.id} ?selected=${i === this.activeIndex}
+                  @click=${() => this.commitInline(item)}
+                >${item.label}</u-option>
+              `)}
+      </u-popover>
+
+      <u-dialog placement="center" @hide=${this.handleDialogHide}>
+        <span slot="header">${this.dialogTitle ?? messages.text("pickerDialogTitle")}</span>
+        <slot name="header"></slot>
+        <div class="dialog-search">
+          <input type="text" .value=${live(this.dialogQuery)}
+            @input=${this.handleDialogSearchInput}
+          />
+        </div>
+        ${this.dialogError ? html`<div class="dialog-error">${messages.text("pickerSearchError")}</div>` : ""}
+        <div class="dialog-table-wrap">
+          <u-rich-table
+            .columns=${this.columns}
+            .data=${this.dialogItems.map((item) => ({
+			...item,
+			_id: item.id
+		}))}
+            .loading=${this.dialogLoading}
+            @row-activate=${this.handleRowActivate}
+            @dblclick=${this.handleRowDblClick}
+          ></u-rich-table>
+        </div>
+        <slot name="footer">
+          <div class="dialog-footer">
+            <u-button variant="ghost" @click=${() => this.dialogEl?.hide()}
+            >${messages.text("pickerCancel")}</u-button>
+            <u-button color="primary" ?disabled=${!this.pendingId}
+              @click=${this.confirmDialogSelection}
+            >${messages.text("pickerConfirm")}</u-button>
+          </div>
+        </slot>
+      </u-dialog>
+    `;
+	}
+	async runInlineSearch(query) {
+		const seq = ++this.inlineSearchSeq;
+		this.loading = true;
+		this.error = false;
+		this.popoverEl?.show(this.containerEl);
+		try {
+			const results = await this.search(query);
+			if (seq !== this.inlineSearchSeq) return;
+			this.items = results;
+			await this.updateComplete;
+			if (results.length > 0) this.popoverEl?.show(this.containerEl);
+			else this.popoverEl?.hide();
+		} catch {
+			if (seq !== this.inlineSearchSeq) return;
+			this.items = [];
+			this.error = true;
+			await this.updateComplete;
+			this.popoverEl?.show(this.containerEl);
+		} finally {
+			if (seq === this.inlineSearchSeq) this.loading = false;
+		}
+	}
+	commitInline(item) {
+		this._selectedItem = item;
+		this.query = item.label;
+		const changed = this.value !== item.id;
+		this.value = item.id;
+		this.items = [];
+		this.popoverEl?.hide();
+		if (changed) this.emitChange();
+	}
+	async runDialogSearch(query) {
+		const seq = ++this.dialogSearchSeq;
+		this.dialogLoading = true;
+		this.dialogError = false;
+		try {
+			const results = await this.search(query);
+			if (seq !== this.dialogSearchSeq) return;
+			this.dialogItems = results;
+		} catch {
+			if (seq !== this.dialogSearchSeq) return;
+			this.dialogItems = [];
+			this.dialogError = true;
+		} finally {
+			if (seq === this.dialogSearchSeq) this.dialogLoading = false;
+		}
+	}
+	commitFromDialog(item) {
+		this._selectedItem = item;
+		this.query = item.label;
+		const changed = this.value !== item.id;
+		this.value = item.id;
+		this.dialogEl?.hide();
+		if (changed) this.emitChange();
+	}
+	emitChange() {
+		if (!this.novalidate) this.validate();
+		this.dispatchEvent(new Event("change", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		if (changedProperties.has("value")) this.internals?.setFormValue(this.value ?? "");
+	}
+	setValidity() {
+		let flags = {};
+		let message = "";
+		if (this.required && !this.value) {
+			flags = { valueMissing: true };
+			message = Locale.getValue("valueMissing");
+		}
+		this.commit(flags, message, this.containerEl ?? void 0);
+	}
+	reset() {
+		this.value = void 0;
+		this.query = "";
+		this._selectedItem = null;
+		this.invalid = false;
+	}
+};
+__decorate([property({ attribute: false }), __decorateMetadata("design:type", Function)], URecordPicker.prototype, "search", void 0);
+__decorate([property({ type: Array }), __decorateMetadata("design:type", Array)], URecordPicker.prototype, "columns", void 0);
+__decorate([property({
+	type: String,
+	attribute: "dialog-title"
+}), __decorateMetadata("design:type", String)], URecordPicker.prototype, "dialogTitle", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], URecordPicker.prototype, "placeholder", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "clearable", void 0);
+__decorate([property({ type: Number }), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "debounce", void 0);
+__decorate([query(".container", true), __decorateMetadata("design:type", typeof HTMLElement === "undefined" ? Object : HTMLElement)], URecordPicker.prototype, "containerEl", void 0);
+__decorate([query("input.main-input", true), __decorateMetadata("design:type", typeof HTMLInputElement === "undefined" ? Object : HTMLInputElement)], URecordPicker.prototype, "inputEl", void 0);
+__decorate([query("u-popover", true), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "popoverEl", void 0);
+__decorate([query("u-dialog", true), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "dialogEl", void 0);
+__decorate([query("u-rich-table", true), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "tableEl", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "query", void 0);
+__decorate([state(), __decorateMetadata("design:type", Array)], URecordPicker.prototype, "items", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "loading", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "activeIndex", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "error", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "dialogQuery", void 0);
+__decorate([state(), __decorateMetadata("design:type", Array)], URecordPicker.prototype, "dialogItems", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "dialogLoading", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "pendingId", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], URecordPicker.prototype, "dialogError", void 0);
+URecordPicker = __decorate([customElement("u-record-picker")], URecordPicker);
+//#endregion
+export { URecordPicker };

package/dist/components/u-record-picker/styles.d.ts

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

package/dist/components/u-record-picker/styles.js

@@ -0,0 +1,83 @@
+import { css } from "lit";
+//#region src/components/u-record-picker/styles.ts
+var styles = css`
+  :host {
+    display: inline-block;
+  }
+
+  .container {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+  }
+
+  .container input {
+    flex: 1;
+    min-width: 0;
+    border: none;
+    outline: none;
+    background: transparent;
+    font: inherit;
+    color: inherit;
+  }
+
+  .suffix-item {
+    cursor: pointer;
+    flex: none;
+  }
+
+  u-popover {
+    display: block;
+    max-height: var(--record-picker-popover-max-height, 50vh);
+    overflow: auto;
+  }
+
+  .no-results {
+    padding: 0.5rem 0.75rem;
+    opacity: 0.6;
+    font-size: 0.875rem;
+  }
+
+  .popover-loading {
+    padding: 0.5rem 0.75rem;
+    display: flex;
+    justify-content: center;
+  }
+
+  .dialog-error {
+    padding: 0.5rem 0.75rem;
+    margin-bottom: 0.5rem;
+    color: var(--u-color-danger, #b91c1c);
+    font-size: 0.875rem;
+  }
+
+  .dialog-search {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding-bottom: 0.75rem;
+  }
+
+  .dialog-search input {
+    flex: 1;
+    min-width: 0;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid currentColor;
+    border-radius: 0.25rem;
+    font: inherit;
+  }
+
+  .dialog-table-wrap {
+    min-height: 16rem;
+    max-height: 60vh;
+    overflow: auto;
+  }
+
+  .dialog-footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.5rem;
+  }
+`;
+//#endregion
+export { styles };

package/dist/components/u-record-picker/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One searchable/selectable record. `id` is the form value; `label` is what the inline
+ * dropdown displays. Extra fields are addressed by `URecordPickerProps.columns[].key` for the
+ * lookup dialog's table — the shape those fields take is entirely up to `search()`'s caller.
+ */
+export interface PickerItem {
+    id: string;
+    label: string;
+    [key: string]: unknown;
+}

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

@@ -1,5 +1,5 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.144.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.146.0/helpers/esm/decorate.js";
 import { messages } from "../../utilities/messages.js";
 import { richTableStyles } from "./styles.js";
 import { parseTSV, toTSV } from "./utils/clipboard.js";

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './components/data-view/UDataView';
 export * from './components/simple-sheet/USimpleSheet';
 export * from './components/u-rich-table/URichTable';
+export * from './components/u-record-picker/URecordPicker';
 /**
  * `URichTable` 의 공개 API 가 요구하는 타입.
  *
@@ -13,3 +14,4 @@ export * from './components/u-rich-table/URichTable';
  * `URichTable` 만 타입을 `types.ts` 로 분리해 배럴이 지나치고 있었다.
  */
 export type { ColumnDef, CellPosition, SortState, FilterState, RichTableEventMap, } from './components/u-rich-table/types';
+export type { PickerItem } from './components/u-record-picker/types';

package/dist/index.js

@@ -2,4 +2,5 @@ import "./utilities/shadowDomProtection.js";
 import { UDataView } from "./components/data-view/UDataView.js";
 import { USimpleSheet } from "./components/simple-sheet/USimpleSheet.js";
 import { URichTable } from "./components/u-rich-table/URichTable.js";
-export { UDataView, URichTable, USimpleSheet };
+import { URecordPicker } from "./components/u-record-picker/URecordPicker.js";
+export { UDataView, URecordPicker, URichTable, USimpleSheet };

package/dist/utilities/messages.d.ts

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

package/dist/utilities/messages.js

@@ -11,7 +11,12 @@ messages.register("en", {
 	noMatch: "No matching item",
 	selected: "{count} selected",
 	selectedAcrossPages: "{count} selected ({onPage} on this page)",
-	rowsPerPage: "{size} rows"
+	rowsPerPage: "{size} rows",
+	pickerDialogTitle: "Select a record",
+	pickerFind: "Find",
+	pickerCancel: "Cancel",
+	pickerConfirm: "Confirm",
+	pickerSearchError: "Search failed. Try again."
 });
 messages.register("ko", {
 	empty: "데이터가 없습니다",
@@ -23,7 +28,12 @@ messages.register("ko", {
 	noMatch: "일치하는 항목 없음",
 	selected: "{count}건 선택됨",
 	selectedAcrossPages: "{count}건 선택됨 (이 페이지 {onPage}건)",
-	rowsPerPage: "{size}행"
+	rowsPerPage: "{size}행",
+	pickerDialogTitle: "레코드 선택",
+	pickerFind: "찾기",
+	pickerCancel: "취소",
+	pickerConfirm: "확인",
+	pickerSearchError: "검색에 실패했습니다. 다시 시도해 주세요."
 });
 //#endregion
 export { messages };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/data-components",
   "description": "iyulab data visualization components",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "keywords": [
     "iyulab",
     "web-components",
@@ -39,7 +39,8 @@
     },
     "./simple-sheet": "./dist/components/simple-sheet/USimpleSheet.js",
     "./data-view": "./dist/components/data-view/UDataView.js",
-    "./u-rich-table": "./dist/components/u-rich-table/URichTable.js"
+    "./u-rich-table": "./dist/components/u-rich-table/URichTable.js",
+    "./u-record-picker": "./dist/components/u-record-picker/URecordPicker.js"
   },
   "sideEffects": [
     "./dist/components/data-view/UDataView.js",
@@ -48,6 +49,8 @@
     "./src/components/simple-sheet/USimpleSheet.ts",
     "./dist/components/u-rich-table/URichTable.js",
     "./src/components/u-rich-table/URichTable.ts",
+    "./dist/components/u-record-picker/URecordPicker.js",
+    "./src/components/u-record-picker/URecordPicker.ts",
     "./dist/index.js",
     "./src/index.ts",
     "./dist/init.js",

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

@@ -1,15 +1,15 @@
 ---
 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.
+description: Data-oriented web components built on Lit — a server-paged rich table with inline editing and cross-page selection, a spreadsheet-like grid, a multi-layout data viewer, and a remote-search record picker. Use when working with @iyulab/data-components package.
 license: MIT
 metadata:
   author: iyulab
-  version: "0.13.0"
+  version: "0.18.0"
 ---
 
 # @iyulab/data-components
 
-Three custom elements for displaying and editing tabular data. Built on
+Four custom elements for displaying and editing tabular data. Built on
 [Lit](https://lit.dev/); usable from any framework or plain HTML.
 
 ## Install
@@ -25,6 +25,7 @@ npm install @iyulab/data-components
 | `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-record-picker` | The user needs to **pick one record** from a remote-searched list — an inline typeahead dropdown or a modal lookup dialog, sharing one `search` callback | [record-picker.md](references/components/record-picker.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

package/skills/iyulab-data-components/references/components/record-picker.md

@@ -0,0 +1,84 @@
+# u-record-picker
+
+```ts
+import '@iyulab/data-components/dist/components/u-record-picker/URecordPicker.js';
+```
+
+**Tag:** `u-record-picker`
+
+Form control that picks one record from a remote-searched list. Typing filters an inline
+dropdown; Enter (with nothing highlighted) or the trailing find button opens a modal lookup
+dialog backed by [`u-rich-table`](./rich-table.md). Form-associated.
+
+```html
+<u-record-picker label="Owner" placeholder="Search people…" clearable></u-record-picker>
+```
+
+```ts
+const picker = document.querySelector('u-record-picker')!;
+picker.search = async (query) => {
+  const res = await fetch(`/api/people?q=${encodeURIComponent(query)}`);
+  const rows = await res.json();
+  return rows.map((r) => ({ id: r.id, label: r.name, ...r }));
+};
+picker.columns = [                 // used by the lookup dialog's u-rich-table
+  { key: 'name',  label: 'Name' },
+  { key: 'email', label: 'Email' },
+];
+```
+
+The inline dropdown and the lookup dialog share the single `search` callback — one async
+lookup, two entry points. Both keyboard (`ArrowDown`/`ArrowUp`/`Enter`/`Escape` inline) and
+mouse work; a single click on a dialog row previews the selection without closing the dialog,
+and only the Confirm button or a row double-click commits it.
+
+## Display only vs. actionable
+
+The dialog's table only previews and commits a row — it does not expose `u-rich-table`'s own
+edit affordances. If a `columns` entry marks a column `editable`, a double-click on that cell
+enters cell-edit mode **and** commits the dialog selection at the same time (the two gestures
+are not distinguished) — avoid `editable` columns in `u-record-picker`'s `columns` until this
+is resolved.
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `search` | `(query: string) => Promise<PickerItem[]>` | — | — | Async lookup, shared by the inline dropdown and the dialog's search bar. Required |
+| `columns` | `ColumnDef[]` | `[]` | — | Column definitions for the lookup dialog's `u-rich-table` (same shape as `u-rich-table`) |
+| `dialogTitle` | `string` | — | — | Lookup dialog header title (attribute: `dialog-title`). Defaults to a localized "Select a record" |
+| `placeholder` | `string` | — | — | Placeholder text for the main input |
+| `clearable` | `boolean` | `false` | ✓ | Show a clear ("x") button when a value is selected |
+| `debounce` | `number` | `250` | — | Inline-dropdown search debounce, in ms |
+| `value` | `string` | — | — | Selected record's id |
+| `disabled` | `boolean` | `false` | ✓ | Disable |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed |
+| `name` | `string` | — | — | Form field name |
+| `label` | `string` | — | — | Field label |
+| `description` | `string` | — | — | Helper text |
+
+`selectedItem` (read-only getter) returns the full `PickerItem` behind `.value`, or `null`
+before any selection.
+
+## PickerItem
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Value committed to `.value` and the form |
+| `label` | `string` | Text shown in the input and dropdown once selected |
+| `...rest` | `any` | Any other fields the app's `search` result carries — read them from `.selectedItem` or a `u-rich-table` column |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when the selected record changes (bubbles, composed, non-cancelable — same contract as `u-select`/`u-input`). Read `.value` (id) and `.selectedItem` (full record) from the target |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `header` | Extra content above the dialog's search bar |
+| `footer` | Replaces the dialog's default Cancel/Confirm buttons |