@iyulab/data-components 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.5.0] - 2026-06-10
+
+### Added
+- React 일급 래퍼 서브패스 `@iyulab/data-components/react` (`@lit/react` createComponent 기반)
+  - `USimpleSheetReact` / `UDataViewReact` / `URichTableReact`
+  - rich property를 JSX props로 직접 전달, 커스텀 이벤트는 타입드 `onXxx` props로 노출
+    (USimpleSheet `onChange`, URichTable은 `RichTableEventMap` 9종 전부)
+  - `@lit/react`, `react`는 optional peerDependency — React 미사용 소비자에 영향 없음
+- README에 React 사용법 및 TypeScript 직접 사용(HTMLElementTagNameMap) 안내 추가
+
+### Fixed
+- `sideEffects`가 dist 경로만 나열해 빌드 시 `shadowDomProtection` 자동 초기화 import가
+  번들에서 제거되던 문제 수정 (src 경로 추가) — 0.4.x 배포본에서 Shadow DOM 스타일 보호가
+  실제로 동작하지 않던 잠재 결함
+
 ## [0.4.1] - 2026-05-07
 
 ### Fixed

package/README.md

@@ -77,6 +77,49 @@ npm install @iyulab/data-components
 ></u-data-view>
 ```
 
+## React
+
+`@lit/react` 기반 일급 래퍼를 `/react` 서브패스로 제공합니다. rich property(`data`, `columns` 등)를
+JSX props로 직접 전달할 수 있고, 커스텀 이벤트는 `onXxx` props로 받습니다 — ref + `useEffect`
+브리지가 필요 없습니다.
+
+```bash
+npm install @iyulab/data-components @lit/react react
+```
+
+```tsx
+import { USimpleSheetReact, type SheetColumn } from '@iyulab/data-components/react';
+
+const columns: SheetColumn[] = [
+  { key: 'name',  label: '이름',   width: 150 },
+  { key: 'email', label: '이메일', width: 220 },
+];
+
+export function MySheet() {
+  return (
+    <USimpleSheetReact
+      style={{ height: 400 }}
+      columns={columns}
+      data={[['홍길동', 'hong@example.com']]}
+      rows={25}
+      onChange={(e) => console.log(e.detail.data)}
+    />
+  );
+}
+```
+
+`URichTableReact`는 `RichTableEventMap`의 모든 이벤트(`onRowUpdate`, `onSortChange`,
+`onSelectionChange` 등)를 타입드 props로 노출합니다. `UDataViewReact`도 동일하게 제공됩니다.
+
+타입스크립트만 필요하다면 래퍼 없이도 엘리먼트 클래스와 `HTMLElementTagNameMap` 증강이
+메인 엔트리에서 제공됩니다:
+
+```typescript
+import type { USimpleSheet } from '@iyulab/data-components';
+
+const sheet = document.querySelector('u-simple-sheet'); // USimpleSheet | null 로 추론
+```
+
 ## Documentation
 
 - [USimpleSheet](./docs/USimpleSheet.md)

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

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.127.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.133.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.127.0/helpers → _@oxc-project_runtime@0.133.0/helpers/esm}/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.127.0/helpers/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.133.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.127.0/helpers/decorateMetadata.js";
-import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.127.0/helpers/decorate.js";
+import { __decorateMetadata } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorateMetadata.js";
+import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorate.js";
 import { html } from "lit";
 import { customElement, property, state } 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.127.0/helpers/decorateMetadata.js";
-import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.127.0/helpers/decorate.js";
+import { __decorateMetadata } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorateMetadata.js";
+import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorate.js";
 import { styles } from "./USimpleSheet.styles.js";
 import { html } from "lit";
 import { customElement, property, state } from "lit/decorators.js";

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

@@ -1,5 +1,5 @@
-import { __decorateMetadata } from "../../_virtual/_@oxc-project_runtime@0.127.0/helpers/decorateMetadata.js";
-import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.127.0/helpers/decorate.js";
+import { __decorateMetadata } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorateMetadata.js";
+import { __decorate } from "../../_virtual/_@oxc-project_runtime@0.133.0/helpers/esm/decorate.js";
 import { richTableStyles } from "./styles.js";
 import { parseTSV, toTSV } from "./utils/clipboard.js";
 import { LitElement, html } from "lit";

package/dist/index.js

@@ -1,3 +1,4 @@
+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";

package/dist/react.d.ts

@@ -0,0 +1,29 @@
+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<{
+        data: string[][];
+    }>>;
+}>;
+/** UDataView React 래퍼 */
+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"]>;
+}>;
+export { USimpleSheet, UDataView, URichTable };
+export type { SheetColumn } from './components/simple-sheet/USimpleSheet';
+export type { DataColumn, ViewMode } from './components/data-view/UDataView';
+export type { ColumnDef, CellPosition, SortState, FilterState, RichTableEventMap, } from './components/u-rich-table/types';

package/dist/react.js

@@ -0,0 +1,48 @@
+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";
+import React from "react";
+import { createComponent } from "@lit/react";
+//#region src/react.ts
+/**
+* React 래퍼 엔트리 (`@iyulab/data-components/react`)
+*
+* `@lit/react` createComponent 기반 — rich property(`data`, `columns` 등)를
+* JSX props로 직접 전달할 수 있고, 커스텀 이벤트는 `onXxx` props로 노출됩니다.
+*
+* react / @lit/react 는 optional peerDependency — 이 서브패스를 import하는
+* React 소비자에게만 필요합니다.
+*/
+/** USimpleSheet React 래퍼 — `change` 이벤트는 `onChange`로 노출 */
+var USimpleSheetReact = createComponent({
+	tagName: "u-simple-sheet",
+	elementClass: USimpleSheet,
+	react: React,
+	events: { onChange: "change" }
+});
+/** UDataView React 래퍼 */
+var UDataViewReact = createComponent({
+	tagName: "u-data-view",
+	elementClass: UDataView,
+	react: React
+});
+/** URichTable React 래퍼 — RichTableEventMap의 모든 이벤트를 onXxx로 노출 */
+var URichTableReact = createComponent({
+	tagName: "u-rich-table",
+	elementClass: URichTable,
+	react: React,
+	events: {
+		onSelectionChange: "selection-change",
+		onRowCreate: "row-create",
+		onRowUpdate: "row-update",
+		onRowDelete: "row-delete",
+		onRowExpand: "row-expand",
+		onSortChange: "sort-change",
+		onFilterChange: "filter-change",
+		onPageChange: "page-change",
+		onPaste: "paste"
+	}
+});
+//#endregion
+export { UDataView, UDataViewReact, URichTable, URichTableReact, USimpleSheet, USimpleSheetReact };

package/dist/utilities/shadowDomProtection.js

@@ -0,0 +1,99 @@
+//#region src/utilities/shadowDomProtection.ts
+/**
+* Shadow DOM Style Protection
+*
+* Protects Lit component styles from being overwritten by Vite HMR.
+* When DevExtreme or other libraries load CSS, Vite HMR may clear/replace
+* Shadow DOM's adoptedStyleSheets, causing Lit component styles to be lost.
+*
+* This module intercepts adoptedStyleSheets setter to:
+* 1. Detect and save Lit styles (identified by :host selector)
+* 2. Block HMR reset attempts that would clear Lit styles
+* 3. Merge Lit styles with other styles (like DevExtreme)
+* 4. Protect registered custom stylesheets from being lost during re-renders
+*/
+var isInitialized = false;
+var protectedCustomStylesheets = /* @__PURE__ */ new Set();
+/**
+* Check if a stylesheet is a protected custom stylesheet
+*/
+function isProtectedCustomStylesheet(sheet) {
+	return protectedCustomStylesheets.has(sheet);
+}
+/**
+* Check if a stylesheet is a Lit component stylesheet
+* Lit styles typically start with :host selector
+*/
+function isLitStyleSheet(sheet) {
+	try {
+		if (!sheet.cssRules || sheet.cssRules.length === 0) return false;
+		return sheet.cssRules[0].cssText.startsWith(":host");
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if the sheets array is empty or an HMR reset attempt
+* Vite HMR may set adoptedStyleSheets to empty array or sheets without rules
+*/
+function isEmptyOrHMRReset(sheets) {
+	if (!sheets || sheets.length === 0) return true;
+	return sheets.every((sheet) => {
+		try {
+			return !sheet.cssRules || sheet.cssRules.length === 0;
+		} catch {
+			return true;
+		}
+	});
+}
+/**
+* Initialize Shadow DOM style protection
+* Should be called before any Lit components are loaded
+*/
+function initShadowDomProtection() {
+	if (isInitialized) return;
+	if (typeof window === "undefined") return;
+	const originalDescriptor = Object.getOwnPropertyDescriptor(ShadowRoot.prototype, "adoptedStyleSheets");
+	if (!originalDescriptor) {
+		console.warn("[data-components] adoptedStyleSheets descriptor not found");
+		return;
+	}
+	const protectedLitStylesMap = /* @__PURE__ */ new WeakMap();
+	Object.defineProperty(ShadowRoot.prototype, "adoptedStyleSheets", {
+		get() {
+			return originalDescriptor.get?.call(this) ?? [];
+		},
+		set(sheets) {
+			const savedLitStyles = protectedLitStylesMap.get(this) || [];
+			const newLitStyles = sheets?.filter(isLitStyleSheet) || [];
+			const newNonLitStyles = sheets?.filter((s) => !isLitStyleSheet(s)) || [];
+			if (newLitStyles.length > 0) protectedLitStylesMap.set(this, [...newLitStyles]);
+			const protectedSheets = Array.from(protectedCustomStylesheets);
+			if (isEmptyOrHMRReset(sheets) && (savedLitStyles.length > 0 || protectedSheets.length > 0)) {
+				const preserved = [...savedLitStyles, ...protectedSheets.filter((s) => !savedLitStyles.includes(s))];
+				originalDescriptor.set?.call(this, preserved);
+				return;
+			}
+			if (savedLitStyles.length > 0 && newLitStyles.length === 0 && newNonLitStyles.length > 0) {
+				const nonProtectedNewStyles = newNonLitStyles.filter((s) => !isProtectedCustomStylesheet(s));
+				const mergedSheets = [
+					...savedLitStyles,
+					...protectedSheets.filter((s) => !savedLitStyles.includes(s)),
+					...nonProtectedNewStyles.filter((s) => !protectedSheets.includes(s))
+				];
+				originalDescriptor.set?.call(this, mergedSheets);
+				return;
+			}
+			const finalSheets = sheets ? [...sheets] : [];
+			protectedSheets.forEach((ps) => {
+				if (!finalSheets.includes(ps)) finalSheets.push(ps);
+			});
+			originalDescriptor.set?.call(this, finalSheets);
+		},
+		configurable: true,
+		enumerable: true
+	});
+	isInitialized = true;
+}
+initShadowDomProtection();
+//#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/data-components",
   "description": "iyulab data visualization components",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "keywords": [
     "iyulab",
     "web-components",
@@ -29,11 +29,20 @@
     },
     "./dist/*": "./dist/*",
     "./init": "./dist/init.js",
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
     "./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"
   },
   "sideEffects": [
+    "./src/utilities/shadowDomProtection.ts",
+    "./src/components/data-view/UDataView.ts",
+    "./src/components/simple-sheet/USimpleSheet.ts",
+    "./src/components/u-rich-table/URichTable.ts",
+    "./src/init.ts",
     "./dist/utilities/shadowDomProtection.js",
     "./dist/components/data-view/UDataView.js",
     "./dist/components/simple-sheet/USimpleSheet.js",
@@ -45,18 +54,33 @@
     "build": "eslint && vite build"
   },
   "dependencies": {
-    "@iyulab/components": "^1.0.4",
-    "lit": "^3.3.2"
+    "@iyulab/components": "^1.0.6",
+    "lit": "^3.3.3"
+  },
+  "peerDependencies": {
+    "@lit/react": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@lit/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
-    "@types/node": "^25.6.0",
+    "@lit/react": "^1.0.8",
+    "@types/react": "^19.2.14",
+    "@types/node": "^25.8.0",
     "eslint": "^9.39.4",
     "glob": "^13.0.6",
-    "globals": "^17.5.0",
+    "globals": "^17.6.0",
+    "react": "^19.2.6",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.2",
-    "vite": "^8.0.8",
-    "vite-plugin-dts": "^4.5.4"
+    "typescript-eslint": "^8.59.3",
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.0"
   }
 }