@iyulab/components 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.9.0] - 2026-07-28
+
+### Fixed
+- **열린 팝오버가 페이지 스크롤 한 번에 닫히던 결함 수정** (u-select listbox·u-input combobox 실사용 및 E2E 구동 불능 — U-Platform 실측, ISSUE-node-packages-20260724-uselect-playwright-driveability). `UPopover.dismiss` 기본값의 `scroll` 이 document 캡처 단계로 등록되는 한편 `UFloatingElement.show()` 는 **모든** 플로팅 엘리먼트에 floating-ui `autoUpdate`(스크롤 시 앵커 추종 재배치)를 설치한다 — 같은 스크롤 이벤트에 재배치와 닫기가 동시에 걸리고 닫기가 이기는 자기모순이었다. 이제 `scroll` 은 **앵커가 스크롤로 의미를 잃을 때만** 닫는다: 실제 엘리먼트에 앵커된 팝오버(드롭다운·제안 목록·서브메뉴·툴팁)는 재배치되어 열린 채 유지되고, `trigger="contextmenu"` 의 좌표 기반 가상 앵커는 종전대로 닫힌다. Playwright 의 "scroll into view" 가 목록을 닫아 `getByRole('option').click()` 이 완주하지 못하던 문제도 함께 해소된다. 회귀 테스트 3건 추가.
+- **`dismiss: 'resize'` 도 같은 원칙으로 정합** — `autoUpdate` 는 `ancestorResize` 로 window 리사이즈도 구독해 재배치하므로 scroll 과 동일한 자기모순이었다. 이제 리사이즈도 좌표 기반 가상 앵커에서만 닫는다. 이로써 모바일에서 `u-select searchable` 의 검색 입력을 탭할 때 가상 키보드가 레이아웃 뷰포트를 줄이며 발생시키는 리사이즈로 드롭다운이 닫히던 문제가 해소된다. 회귀 테스트 2건 추가.
+
+- **React 래퍼가 `ref` 를 타입 수준에서 거부하던 문제 수정** — 생성된 `.d.ts` 가 `React.ForwardRefExoticComponent<P>` 를 쓰면서 P 에 `React.RefAttributes` 를 넣지 않았다. `ForwardRefExoticComponent<P>` 는 ref 를 자동으로 더해 주지 않으므로, `@lit/react` 가 런타임에 ref 를 정상 전달하는데도(`ReactWebComponent` 자신은 `PropsWithoutRef<…> & React.RefAttributes<I>` 로 선언돼 있다) `<UButton ref={…} />` 가 TS2322 로 거부됐다. 이제 42개 래퍼 전부가 ref 를 받으며, ref 타입은 `HTMLElement` 가 아니라 **해당 엘리먼트 클래스**로 좁혀진다. 신설 React 타입 스모크가 첫 실행에서 잡아낸 결함이다.
+
+### Added
+- **React strict 소비 타입 스모크** — 소비자가 React 19 + TS strict 에서 겪은 래퍼 결함들(JSX children TS2747, 이벤트 핸들러 교집합, 위 ref 누락)은 전부 **런타임에 드러나지 않는 타입 실패**라 vitest 로는 잡히지 않는다. `tests/types/react-consumption.tsx` 를 두고 `tsconfig.react-smoke.json` 전용 프로젝트로 컴파일하며, 검증 대상이 빌드 산출물(`dist/react/*.d.ts`)이므로 `build` 파이프라인 끝에 건다(`npm run build` 에 포함). 소비자와 동일한 진입점 `@iyulab/components/react` 를 통과시켜 `exports` 맵까지 함께 검증한다.
+- **앵커 이탈 시 팝오버 자동 숨김** — 위 수정으로 실앵커 팝오버가 스크롤에 닫히지 않게 되면서 드러난 케이스 대응. `strategy="fixed"` 팝오버는 overflow 조상에 클립되지 않으므로(그것이 fixed 를 쓰는 이유), 앵커가 스크롤 패널 밖으로 나가면 팝오버만 화면에 남아 무관한 콘텐츠를 덮을 수 있었다. floating-ui `hide` middleware 를 `UFloatingElement.reposition()` 에 도입해, 앵커가 클리핑 영역(스크롤 컨테이너·뷰포트)을 완전히 벗어나면 `anchor-hidden` 속성이 붙고 엘리먼트가 숨겨진다. **닫히지는 않으므로**(`open` 유지) 되돌려 스크롤하면 열린 상태 그대로 복귀한다. `anchor-hidden` 은 읽기 전용 파생 상태이며 스타일 훅으로 사용할 수 있다. 회귀 테스트 2건 추가.
+
 ## [1.8.1] - 2026-07-24
 
 ### Fixed

package/dist/components/UFloatingElement.d.ts

@@ -8,6 +8,11 @@ export type FloatingStrategy = 'absolute' | 'fixed';
  *
  * @event show - 엘리먼트가 표시되기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 표시가 취소됩니다.
  * @event hide - 엘리먼트가 숨겨지기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 숨김이 취소됩니다.
+ *
+ * @attr {boolean} anchor-hidden - **읽기 전용 파생 상태**(설정하지 마세요). 앵커가 클리핑
+ *   영역(스크롤 컨테이너·뷰포트) 밖으로 완전히 벗어난 동안 자동으로 붙습니다. 이때 엘리먼트는
+ *   숨겨지지만 **닫히지는 않으며**(`open` 유지), 앵커가 다시 보이면 그대로 복귀합니다.
+ *   스타일 훅으로 사용할 수 있습니다: `my-popover[anchor-hidden] { … }`
  */
 export declare class UFloatingElement extends UElement {
     static styles: CSSResultGroup;

package/dist/components/UFloatingElement.js

@@ -4,14 +4,19 @@ import { styles } from "./UFloatingElement.styles.js";
 import __decorateMetadata from "../_virtual/_@oxc-project_runtime@0.139.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../_virtual/_@oxc-project_runtime@0.139.0/helpers/esm/decorate.js";
 import { property, state } from "lit/decorators.js";
-import { arrow, autoPlacement, autoUpdate, computePosition, flip, offset, shift } from "@floating-ui/dom";
+import { arrow, autoPlacement, autoUpdate, computePosition, flip, hide, offset, shift } from "@floating-ui/dom";
 //#region src/components/UFloatingElement.ts
 /**
 * UFloatingElement는 팝오버, 툴팁 등 화면에 떠 있는 엘리먼트를 구현하기 위한 기본 클래스입니다.
 * 이 클래스를 상속하여 커스텀 팝오버 컴포넌트를 만들 수 있습니다.
-* 
+*
 * @event show - 엘리먼트가 표시되기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 표시가 취소됩니다.
 * @event hide - 엘리먼트가 숨겨지기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 숨김이 취소됩니다.
+*
+* @attr {boolean} anchor-hidden - **읽기 전용 파생 상태**(설정하지 마세요). 앵커가 클리핑
+*   영역(스크롤 컨테이너·뷰포트) 밖으로 완전히 벗어난 동안 자동으로 붙습니다. 이때 엘리먼트는
+*   숨겨지지만 **닫히지는 않으며**(`open` 유지), 앵커가 다시 보이면 그대로 복귀합니다.
+*   스타일 훅으로 사용할 수 있습니다: `my-popover[anchor-hidden] { … }`
 */
 var UFloatingElement = class extends UElement {
 	constructor(..._args) {
@@ -134,7 +139,8 @@ var UFloatingElement = class extends UElement {
 				offset(this.offset),
 				shift({ mainAxis: this.shift }),
 				this.placement ? flip() : autoPlacement(),
-				...this.arrowEl ? [arrow({ element: this.arrowEl })] : []
+				...this.arrowEl ? [arrow({ element: this.arrowEl })] : [],
+				hide()
 			]
 		});
 		const config = {
@@ -164,6 +170,7 @@ var UFloatingElement = class extends UElement {
 			top: `${position.y}px`,
 			transformOrigin: config.transform
 		});
+		this.toggleAttribute("anchor-hidden", !!position.middlewareData.hide?.referenceHidden);
 		const arrowData = position.middlewareData.arrow;
 		if (!this.arrowEl || !arrowData) return;
 		Object.assign(this.arrowEl.style, {

package/dist/components/UFloatingElement.styles.js

@@ -34,6 +34,16 @@ var styles = css`
     position: fixed;
   }
 
+  /* 앵커가 클리핑 영역(스크롤 컨테이너·뷰포트) 밖으로 나가 참조를 잃은 동안은 숨긴다.
+     닫지는 않는다 — 앵커가 다시 보이면 열린 상태 그대로 복귀한다.
+     특히 strategy="fixed" 는 overflow 조상에 클립되지 않으므로(그것이 fixed 를 쓰는 이유),
+     이 규칙이 없으면 앵커가 스크롤 패널 밖으로 나간 뒤에도 팝오버만 화면에 남는다.
+     :host([open]) 과 명시도가 같으므로 반드시 그 뒤에 와야 이긴다. */
+  :host([anchor-hidden]) {
+    visibility: hidden;
+    pointer-events: none;
+  }
+
   /* 화살표: clip-path로 삼각형 */
   #arrow {
     position: absolute;

package/dist/components/popover/UPopover.d.ts

@@ -29,8 +29,10 @@ export declare class UPopover extends UFloatingElement {
      * 팝오버를 닫는 조건 (쉼표 구분하여 복수 지정 가능)
      * - `click`: 외부 클릭 시 닫기
      * - `escape`: Escape 키 시 닫기
-     * - `scroll`: 스크롤 시 닫기
-     * - `resize`: 윈도우 리사이즈 시 닫기
+     * - `scroll` / `resize`: 뷰포트 기하 변화로 **앵커가 의미를 잃을 때** 닫기 — 즉
+     *   `contextmenu` 처럼 좌표 기반 가상 앵커에 붙은 경우에만 닫는다. 실제 엘리먼트에 앵커된
+     *   팝오버는 `autoUpdate` 가 스크롤·리사이즈를 따라 재배치하므로 닫지 않는다
+     *   (`isCoordinateAnchored` 참조).
      */
     dismiss: PopoverDismiss[];
     /** 닫기 조건에 포함시킬 이벤트 목록 (쉼표 구분) */
@@ -58,7 +60,32 @@ export declare class UPopover extends UFloatingElement {
     private cancelSafeTimer;
     private handleDocumentClick;
     private handleDocumentKeydown;
+    /**
+     * 현재 표시 중이며 앵커가 **좌표 기반 가상 엘리먼트**인지 여부.
+     *
+     * 뷰포트 기하 변화(스크롤·리사이즈)는 그 자체로 닫기 사유가 아니다. `UFloatingElement.show()`
+     * 가 모든 플로팅 엘리먼트에 `autoUpdate` 를 설치하고, `autoUpdate` 는 조상 스크롤과 리사이즈를
+     * 모두 구독해 재배치한다 — 여기서 hide 하면 재배치 로직과 정면으로 모순된다. 실제로 그 모순이
+     * 열린 listbox(u-select·u-input combobox)를 페이지 스크롤 한 번에 닫아버렸다.
+     * 앵커가 클리핑 영역 밖으로 나가는 경우는 `hide` middleware 가 별도로 처리한다(닫지 않고 숨김).
+     *
+     * 닫아야 하는 경우는 **앵커가 좌표라서 기하 변화에 의미를 잃는 경우**뿐이다 —
+     * `trigger="contextmenu"` 의 가상 앵커는 이벤트 발생 시점의 clientX/clientY 에 고정돼 있어
+     * 콘텐츠가 스크롤·리플로우되면 가리키던 대상과 어긋난다.
+     *
+     * `targetEl` 이 없으면 표시 중이 아니므로 닫을 것도 없다 — 이 가드가 없으면 닫힌 팝오버가
+     * 스크롤 이벤트마다 `hide()`(→ `await updateComplete`) 를 돌려 인스턴스 수만큼 churn 이 된다.
+     * 단 `show()` 는 showDelay 타이머보다 **먼저** `targetEl` 을 세우므로, 가상 앵커의 대기 중
+     * show 취소는 이 가드를 통과해 그대로 보존된다.
+     */
+    private get isCoordinateAnchored();
     private handleDocumentScroll;
+    /**
+     * 리사이즈도 스크롤과 같은 뷰포트 기하 변화다 — `autoUpdate` 가 `ancestorResize` 로 window
+     * 리사이즈를 구독해 재배치하므로 실앵커 팝오버를 닫을 이유가 없다. 닫으면 모바일에서
+     * `u-select searchable` 의 검색 입력을 탭하는 순간 가상 키보드가 레이아웃 뷰포트를 줄이며
+     * 리사이즈를 발생시켜 드롭다운이 닫혀버린다.
+     */
     private handleWindowResize;
     private handlePopoverEvent;
 }

package/dist/components/popover/UPopover.js

@@ -87,9 +87,11 @@ var UPopover = class UPopover extends UFloatingElement {
 			this.hide();
 		};
 		this.handleDocumentScroll = () => {
+			if (!this.isCoordinateAnchored) return;
 			this.hide();
 		};
 		this.handleWindowResize = () => {
+			if (!this.isCoordinateAnchored) return;
 			this.hide();
 		};
 		this.handlePopoverEvent = () => {
@@ -210,6 +212,27 @@ var UPopover = class UPopover extends UFloatingElement {
 		clearTimeout(this.safeTimer);
 		this.safeTimer = void 0;
 	}
+	/**
+	* 현재 표시 중이며 앵커가 **좌표 기반 가상 엘리먼트**인지 여부.
+	*
+	* 뷰포트 기하 변화(스크롤·리사이즈)는 그 자체로 닫기 사유가 아니다. `UFloatingElement.show()`
+	* 가 모든 플로팅 엘리먼트에 `autoUpdate` 를 설치하고, `autoUpdate` 는 조상 스크롤과 리사이즈를
+	* 모두 구독해 재배치한다 — 여기서 hide 하면 재배치 로직과 정면으로 모순된다. 실제로 그 모순이
+	* 열린 listbox(u-select·u-input combobox)를 페이지 스크롤 한 번에 닫아버렸다.
+	* 앵커가 클리핑 영역 밖으로 나가는 경우는 `hide` middleware 가 별도로 처리한다(닫지 않고 숨김).
+	*
+	* 닫아야 하는 경우는 **앵커가 좌표라서 기하 변화에 의미를 잃는 경우**뿐이다 —
+	* `trigger="contextmenu"` 의 가상 앵커는 이벤트 발생 시점의 clientX/clientY 에 고정돼 있어
+	* 콘텐츠가 스크롤·리플로우되면 가리키던 대상과 어긋난다.
+	*
+	* `targetEl` 이 없으면 표시 중이 아니므로 닫을 것도 없다 — 이 가드가 없으면 닫힌 팝오버가
+	* 스크롤 이벤트마다 `hide()`(→ `await updateComplete`) 를 돌려 인스턴스 수만큼 churn 이 된다.
+	* 단 `show()` 는 showDelay 타이머보다 **먼저** `targetEl` 을 세우므로, 가상 앵커의 대기 중
+	* show 취소는 이 가드를 통과해 그대로 보존된다.
+	*/
+	get isCoordinateAnchored() {
+		return !!this.targetEl && !(this.targetEl instanceof Element);
+	}
 };
 __decorate([property({
 	type: Boolean,

package/dist/react/UAlert.d.ts

@@ -6,6 +6,7 @@ import { type HideEventDetail } from '../events/HideEvent';
 export declare const UAlert: React.ForwardRefExoticComponent<
   Omit<Partial<UAlertElement>, keyof React.HTMLAttributes<UAlertElement>>
     & Omit<React.HTMLAttributes<UAlertElement>, 'onShow' | 'onHide'>
+    & React.RefAttributes<UAlertElement>
     & {
   onShow?: (event: CustomEvent<ShowEventDetail>) => void;
   onHide?: (event: CustomEvent<HideEventDetail>) => void;

package/dist/react/UAvatar.d.ts

@@ -4,6 +4,7 @@ import { UAvatar as UAvatarElement } from '../components/avatar/UAvatar';
 export declare const UAvatar: React.ForwardRefExoticComponent<
   Omit<Partial<UAvatarElement>, keyof React.HTMLAttributes<UAvatarElement>>
     & Omit<React.HTMLAttributes<UAvatarElement>, never>
+    & React.RefAttributes<UAvatarElement>
     & {
   }
 >;

package/dist/react/UBadge.d.ts

@@ -4,6 +4,7 @@ import { UBadge as UBadgeElement } from '../components/badge/UBadge';
 export declare const UBadge: React.ForwardRefExoticComponent<
   Omit<Partial<UBadgeElement>, keyof React.HTMLAttributes<UBadgeElement>>
     & Omit<React.HTMLAttributes<UBadgeElement>, never>
+    & React.RefAttributes<UBadgeElement>
     & {
   }
 >;

package/dist/react/UBreadcrumb.d.ts

@@ -4,6 +4,7 @@ import { UBreadcrumb as UBreadcrumbElement } from '../components/breadcrumb/UBre
 export declare const UBreadcrumb: React.ForwardRefExoticComponent<
   Omit<Partial<UBreadcrumbElement>, keyof React.HTMLAttributes<UBreadcrumbElement>>
     & Omit<React.HTMLAttributes<UBreadcrumbElement>, never>
+    & React.RefAttributes<UBreadcrumbElement>
     & {
   }
 >;

package/dist/react/UBreadcrumbItem.d.ts

@@ -5,6 +5,7 @@ import { type NavigateEventDetail } from '../events/NavigateEvent';
 export declare const UBreadcrumbItem: React.ForwardRefExoticComponent<
   Omit<Partial<UBreadcrumbItemElement>, keyof React.HTMLAttributes<UBreadcrumbItemElement>>
     & Omit<React.HTMLAttributes<UBreadcrumbItemElement>, 'onNavigate'>
+    & React.RefAttributes<UBreadcrumbItemElement>
     & {
   onNavigate?: (event: CustomEvent<NavigateEventDetail>) => void;
   }

package/dist/react/UButton.d.ts

@@ -4,6 +4,7 @@ import { UButton as UButtonElement } from '../components/button/UButton';
 export declare const UButton: React.ForwardRefExoticComponent<
   Omit<Partial<UButtonElement>, keyof React.HTMLAttributes<UButtonElement>>
     & Omit<React.HTMLAttributes<UButtonElement>, never>
+    & React.RefAttributes<UButtonElement>
     & {
   }
 >;

package/dist/react/UButtonGroup.d.ts

@@ -4,6 +4,7 @@ import { UButtonGroup as UButtonGroupElement } from '../components/button-group/
 export declare const UButtonGroup: React.ForwardRefExoticComponent<
   Omit<Partial<UButtonGroupElement>, keyof React.HTMLAttributes<UButtonGroupElement>>
     & Omit<React.HTMLAttributes<UButtonGroupElement>, never>
+    & React.RefAttributes<UButtonGroupElement>
     & {
   }
 >;

package/dist/react/UCard.d.ts

@@ -4,6 +4,7 @@ import { UCard as UCardElement } from '../components/card/UCard';
 export declare const UCard: React.ForwardRefExoticComponent<
   Omit<Partial<UCardElement>, keyof React.HTMLAttributes<UCardElement>>
     & Omit<React.HTMLAttributes<UCardElement>, never>
+    & React.RefAttributes<UCardElement>
     & {
   }
 >;

package/dist/react/UCarousel.d.ts

@@ -4,6 +4,7 @@ import { UCarousel as UCarouselElement } from '../components/carousel/UCarousel'
 export declare const UCarousel: React.ForwardRefExoticComponent<
   Omit<Partial<UCarouselElement>, keyof React.HTMLAttributes<UCarouselElement>>
     & Omit<React.HTMLAttributes<UCarouselElement>, never>
+    & React.RefAttributes<UCarouselElement>
     & {
   }
 >;

package/dist/react/UCheckbox.d.ts

@@ -4,6 +4,7 @@ import { UCheckbox as UCheckboxElement } from '../components/checkbox/UCheckbox'
 export declare const UCheckbox: React.ForwardRefExoticComponent<
   Omit<Partial<UCheckboxElement>, keyof React.HTMLAttributes<UCheckboxElement>>
     & Omit<React.HTMLAttributes<UCheckboxElement>, 'onChange'>
+    & React.RefAttributes<UCheckboxElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UChip.d.ts

@@ -6,6 +6,7 @@ import { type RemoveEventDetail } from '../events/RemoveEvent';
 export declare const UChip: React.ForwardRefExoticComponent<
   Omit<Partial<UChipElement>, keyof React.HTMLAttributes<UChipElement>>
     & Omit<React.HTMLAttributes<UChipElement>, 'onPick' | 'onRemove'>
+    & React.RefAttributes<UChipElement>
     & {
   onPick?: (event: CustomEvent<PickEventDetail>) => void;
   onRemove?: (event: CustomEvent<RemoveEventDetail>) => void;

package/dist/react/UCopyButton.d.ts

@@ -4,6 +4,7 @@ import { UCopyButton as UCopyButtonElement } from '../components/copy-button/UCo
 export declare const UCopyButton: React.ForwardRefExoticComponent<
   Omit<Partial<UCopyButtonElement>, keyof React.HTMLAttributes<UCopyButtonElement>>
     & Omit<React.HTMLAttributes<UCopyButtonElement>, 'onCopy'>
+    & React.RefAttributes<UCopyButtonElement>
     & {
   onCopy?: (event: CustomEvent) => void;
   }

package/dist/react/UDialog.d.ts

@@ -4,6 +4,7 @@ import { UDialog as UDialogElement } from '../components/dialog/UDialog';
 export declare const UDialog: React.ForwardRefExoticComponent<
   Omit<Partial<UDialogElement>, keyof React.HTMLAttributes<UDialogElement>>
     & Omit<React.HTMLAttributes<UDialogElement>, never>
+    & React.RefAttributes<UDialogElement>
     & {
   }
 >;

package/dist/react/UDivider.d.ts

@@ -4,6 +4,7 @@ import { UDivider as UDividerElement } from '../components/divider/UDivider';
 export declare const UDivider: React.ForwardRefExoticComponent<
   Omit<Partial<UDividerElement>, keyof React.HTMLAttributes<UDividerElement>>
     & Omit<React.HTMLAttributes<UDividerElement>, never>
+    & React.RefAttributes<UDividerElement>
     & {
   }
 >;

package/dist/react/UDrawer.d.ts

@@ -4,6 +4,7 @@ import { UDrawer as UDrawerElement } from '../components/drawer/UDrawer';
 export declare const UDrawer: React.ForwardRefExoticComponent<
   Omit<Partial<UDrawerElement>, keyof React.HTMLAttributes<UDrawerElement>>
     & Omit<React.HTMLAttributes<UDrawerElement>, never>
+    & React.RefAttributes<UDrawerElement>
     & {
   }
 >;

package/dist/react/UField.d.ts

@@ -4,6 +4,7 @@ import { UField as UFieldElement } from '../components/field/UField';
 export declare const UField: React.ForwardRefExoticComponent<
   Omit<Partial<UFieldElement>, keyof React.HTMLAttributes<UFieldElement>>
     & Omit<React.HTMLAttributes<UFieldElement>, never>
+    & React.RefAttributes<UFieldElement>
     & {
   }
 >;

package/dist/react/UForm.d.ts

@@ -4,6 +4,7 @@ import { UForm as UFormElement } from '../components/form/UForm';
 export declare const UForm: React.ForwardRefExoticComponent<
   Omit<Partial<UFormElement>, keyof React.HTMLAttributes<UFormElement>>
     & Omit<React.HTMLAttributes<UFormElement>, 'onChange'>
+    & React.RefAttributes<UFormElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UIcon.d.ts

@@ -4,6 +4,7 @@ import { UIcon as UIconElement } from '../components/icon/UIcon';
 export declare const UIcon: React.ForwardRefExoticComponent<
   Omit<Partial<UIconElement>, keyof React.HTMLAttributes<UIconElement>>
     & Omit<React.HTMLAttributes<UIconElement>, never>
+    & React.RefAttributes<UIconElement>
     & {
   }
 >;

package/dist/react/UIconButton.d.ts

@@ -4,6 +4,7 @@ import { UIconButton as UIconButtonElement } from '../components/icon-button/UIc
 export declare const UIconButton: React.ForwardRefExoticComponent<
   Omit<Partial<UIconButtonElement>, keyof React.HTMLAttributes<UIconButtonElement>>
     & Omit<React.HTMLAttributes<UIconButtonElement>, never>
+    & React.RefAttributes<UIconButtonElement>
     & {
   }
 >;

package/dist/react/UInput.d.ts

@@ -4,6 +4,7 @@ import { UInput as UInputElement } from '../components/input/UInput';
 export declare const UInput: React.ForwardRefExoticComponent<
   Omit<Partial<UInputElement>, keyof React.HTMLAttributes<UInputElement>>
     & Omit<React.HTMLAttributes<UInputElement>, 'onInput' | 'onChange'>
+    & React.RefAttributes<UInputElement>
     & {
   onInput?: (event: CustomEvent) => void;
   onChange?: (event: CustomEvent) => void;

package/dist/react/UMenu.d.ts

@@ -4,6 +4,7 @@ import { UMenu as UMenuElement } from '../components/menu/UMenu';
 export declare const UMenu: React.ForwardRefExoticComponent<
   Omit<Partial<UMenuElement>, keyof React.HTMLAttributes<UMenuElement>>
     & Omit<React.HTMLAttributes<UMenuElement>, 'onChange'>
+    & React.RefAttributes<UMenuElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UMenuItem.d.ts

@@ -5,6 +5,7 @@ import { type PickEventDetail } from '../events/PickEvent';
 export declare const UMenuItem: React.ForwardRefExoticComponent<
   Omit<Partial<UMenuItemElement>, keyof React.HTMLAttributes<UMenuItemElement>>
     & Omit<React.HTMLAttributes<UMenuItemElement>, 'onPick'>
+    & React.RefAttributes<UMenuItemElement>
     & {
   onPick?: (event: CustomEvent<PickEventDetail>) => void;
   }

package/dist/react/UOption.d.ts

@@ -4,6 +4,7 @@ import { UOption as UOptionElement } from '../components/option/UOption';
 export declare const UOption: React.ForwardRefExoticComponent<
   Omit<Partial<UOptionElement>, keyof React.HTMLAttributes<UOptionElement>>
     & Omit<React.HTMLAttributes<UOptionElement>, never>
+    & React.RefAttributes<UOptionElement>
     & {
   }
 >;

package/dist/react/UPanel.d.ts

@@ -4,6 +4,7 @@ import { UPanel as UPanelElement } from '../components/panel/UPanel';
 export declare const UPanel: React.ForwardRefExoticComponent<
   Omit<Partial<UPanelElement>, keyof React.HTMLAttributes<UPanelElement>>
     & Omit<React.HTMLAttributes<UPanelElement>, never>
+    & React.RefAttributes<UPanelElement>
     & {
   }
 >;

package/dist/react/UPopover.d.ts

@@ -4,6 +4,7 @@ import { UPopover as UPopoverElement } from '../components/popover/UPopover';
 export declare const UPopover: React.ForwardRefExoticComponent<
   Omit<Partial<UPopoverElement>, keyof React.HTMLAttributes<UPopoverElement>>
     & Omit<React.HTMLAttributes<UPopoverElement>, 'onShow' | 'onHide'>
+    & React.RefAttributes<UPopoverElement>
     & {
   onShow?: (event: CustomEvent) => void;
   onHide?: (event: CustomEvent) => void;

package/dist/react/UProgressBar.d.ts

@@ -4,6 +4,7 @@ import { UProgressBar as UProgressBarElement } from '../components/progress-bar/
 export declare const UProgressBar: React.ForwardRefExoticComponent<
   Omit<Partial<UProgressBarElement>, keyof React.HTMLAttributes<UProgressBarElement>>
     & Omit<React.HTMLAttributes<UProgressBarElement>, never>
+    & React.RefAttributes<UProgressBarElement>
     & {
   }
 >;

package/dist/react/UProgressRing.d.ts

@@ -4,6 +4,7 @@ import { UProgressRing as UProgressRingElement } from '../components/progress-ri
 export declare const UProgressRing: React.ForwardRefExoticComponent<
   Omit<Partial<UProgressRingElement>, keyof React.HTMLAttributes<UProgressRingElement>>
     & Omit<React.HTMLAttributes<UProgressRingElement>, never>
+    & React.RefAttributes<UProgressRingElement>
     & {
   }
 >;

package/dist/react/URadio.d.ts

@@ -4,6 +4,7 @@ import { URadio as URadioElement } from '../components/radio/URadio';
 export declare const URadio: React.ForwardRefExoticComponent<
   Omit<Partial<URadioElement>, keyof React.HTMLAttributes<URadioElement>>
     & Omit<React.HTMLAttributes<URadioElement>, 'onChange'>
+    & React.RefAttributes<URadioElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/URating.d.ts

@@ -4,6 +4,7 @@ import { URating as URatingElement } from '../components/rating/URating';
 export declare const URating: React.ForwardRefExoticComponent<
   Omit<Partial<URatingElement>, keyof React.HTMLAttributes<URatingElement>>
     & Omit<React.HTMLAttributes<URatingElement>, 'onChange'>
+    & React.RefAttributes<URatingElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/USelect.d.ts

@@ -4,6 +4,7 @@ import { USelect as USelectElement } from '../components/select/USelect';
 export declare const USelect: React.ForwardRefExoticComponent<
   Omit<Partial<USelectElement>, keyof React.HTMLAttributes<USelectElement>>
     & Omit<React.HTMLAttributes<USelectElement>, 'onChange'>
+    & React.RefAttributes<USelectElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/USkeleton.d.ts

@@ -4,6 +4,7 @@ import { USkeleton as USkeletonElement } from '../components/skeleton/USkeleton'
 export declare const USkeleton: React.ForwardRefExoticComponent<
   Omit<Partial<USkeletonElement>, keyof React.HTMLAttributes<USkeletonElement>>
     & Omit<React.HTMLAttributes<USkeletonElement>, never>
+    & React.RefAttributes<USkeletonElement>
     & {
   }
 >;

package/dist/react/USlider.d.ts

@@ -4,6 +4,7 @@ import { USlider as USliderElement } from '../components/slider/USlider';
 export declare const USlider: React.ForwardRefExoticComponent<
   Omit<Partial<USliderElement>, keyof React.HTMLAttributes<USliderElement>>
     & Omit<React.HTMLAttributes<USliderElement>, 'onChange'>
+    & React.RefAttributes<USliderElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/USpinner.d.ts

@@ -4,6 +4,7 @@ import { USpinner as USpinnerElement } from '../components/spinner/USpinner';
 export declare const USpinner: React.ForwardRefExoticComponent<
   Omit<Partial<USpinnerElement>, keyof React.HTMLAttributes<USpinnerElement>>
     & Omit<React.HTMLAttributes<USpinnerElement>, never>
+    & React.RefAttributes<USpinnerElement>
     & {
   }
 >;

package/dist/react/USplitPanel.d.ts

@@ -5,6 +5,7 @@ import { type ShiftEventDetail } from '../events/ShiftEvent';
 export declare const USplitPanel: React.ForwardRefExoticComponent<
   Omit<Partial<USplitPanelElement>, keyof React.HTMLAttributes<USplitPanelElement>>
     & Omit<React.HTMLAttributes<USplitPanelElement>, 'onShiftStart' | 'onShift' | 'onShiftEnd'>
+    & React.RefAttributes<USplitPanelElement>
     & {
   onShiftStart?: (event: CustomEvent<ShiftEventDetail>) => void;
   onShift?: (event: CustomEvent<ShiftEventDetail>) => void;

package/dist/react/USwitch.d.ts

@@ -4,6 +4,7 @@ import { USwitch as USwitchElement } from '../components/switch/USwitch';
 export declare const USwitch: React.ForwardRefExoticComponent<
   Omit<Partial<USwitchElement>, keyof React.HTMLAttributes<USwitchElement>>
     & Omit<React.HTMLAttributes<USwitchElement>, 'onChange'>
+    & React.RefAttributes<USwitchElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UTab.d.ts

@@ -5,6 +5,7 @@ import { type RemoveEventDetail } from '../events/RemoveEvent';
 export declare const UTab: React.ForwardRefExoticComponent<
   Omit<Partial<UTabElement>, keyof React.HTMLAttributes<UTabElement>>
     & Omit<React.HTMLAttributes<UTabElement>, 'onRemove'>
+    & React.RefAttributes<UTabElement>
     & {
   onRemove?: (event: CustomEvent<RemoveEventDetail>) => void;
   }

package/dist/react/UTabPanel.d.ts

@@ -4,6 +4,7 @@ import { UTabPanel as UTabPanelElement } from '../components/tab-panel/UTabPanel
 export declare const UTabPanel: React.ForwardRefExoticComponent<
   Omit<Partial<UTabPanelElement>, keyof React.HTMLAttributes<UTabPanelElement>>
     & Omit<React.HTMLAttributes<UTabPanelElement>, 'onChange'>
+    & React.RefAttributes<UTabPanelElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UTag.d.ts

@@ -4,6 +4,7 @@ import { UTag as UTagElement } from '../components/tag/UTag';
 export declare const UTag: React.ForwardRefExoticComponent<
   Omit<Partial<UTagElement>, keyof React.HTMLAttributes<UTagElement>>
     & Omit<React.HTMLAttributes<UTagElement>, never>
+    & React.RefAttributes<UTagElement>
     & {
   }
 >;

package/dist/react/UTextarea.d.ts

@@ -4,6 +4,7 @@ import { UTextarea as UTextareaElement } from '../components/textarea/UTextarea'
 export declare const UTextarea: React.ForwardRefExoticComponent<
   Omit<Partial<UTextareaElement>, keyof React.HTMLAttributes<UTextareaElement>>
     & Omit<React.HTMLAttributes<UTextareaElement>, 'onInput' | 'onChange'>
+    & React.RefAttributes<UTextareaElement>
     & {
   onInput?: (event: CustomEvent) => void;
   onChange?: (event: CustomEvent) => void;

package/dist/react/UTooltip.d.ts

@@ -4,6 +4,7 @@ import { UTooltip as UTooltipElement } from '../components/tooltip/UTooltip';
 export declare const UTooltip: React.ForwardRefExoticComponent<
   Omit<Partial<UTooltipElement>, keyof React.HTMLAttributes<UTooltipElement>>
     & Omit<React.HTMLAttributes<UTooltipElement>, 'onShow' | 'onHide'>
+    & React.RefAttributes<UTooltipElement>
     & {
   onShow?: (event: CustomEvent) => void;
   onHide?: (event: CustomEvent) => void;

package/dist/react/UTree.d.ts

@@ -4,6 +4,7 @@ import { UTree as UTreeElement } from '../components/tree/UTree';
 export declare const UTree: React.ForwardRefExoticComponent<
   Omit<Partial<UTreeElement>, keyof React.HTMLAttributes<UTreeElement>>
     & Omit<React.HTMLAttributes<UTreeElement>, 'onChange'>
+    & React.RefAttributes<UTreeElement>
     & {
   onChange?: (event: CustomEvent) => void;
   }

package/dist/react/UTreeItem.d.ts

@@ -8,6 +8,7 @@ import { type CheckEventDetail } from '../events/CheckEvent';
 export declare const UTreeItem: React.ForwardRefExoticComponent<
   Omit<Partial<UTreeItemElement>, keyof React.HTMLAttributes<UTreeItemElement>>
     & Omit<React.HTMLAttributes<UTreeItemElement>, 'onExpand' | 'onCollapse' | 'onPick' | 'onCheck'>
+    & React.RefAttributes<UTreeItemElement>
     & {
   onExpand?: (event: CustomEvent<ExpandEventDetail>) => void;
   onCollapse?: (event: CustomEvent<CollapseEventDetail>) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "keywords": [
     "iyulab",
     "components",
@@ -45,7 +45,8 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "build:plugins": "tsc -p plugins/tsconfig.json",
-    "build": "eslint && vite build && npm run build:plugins"
+    "build": "eslint && vite build && npm run build:plugins && npm run test:react-types",
+    "test:react-types": "tsc -p tsconfig.react-smoke.json"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
@@ -67,6 +68,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/node": "^26.1.1",
+    "@types/react": "^19.2.14",
     "@vitest/browser-playwright": "^4.1.10",
     "eslint": "^9.39.4",
     "eslint-plugin-lit": "^2.3.1",

package/plugins/vite-plugin-react-wrapper.js

@@ -199,11 +199,17 @@ export const ${className} = createComponent({
     // Partial<Element> 은 DOM 프로퍼티(children: HTMLCollection 등)를 포함해 React 의 JSX
     // children/이벤트/className 등과 충돌한다. keyof React.HTMLAttributes 를 제거해 컴포넌트
     // 고유 prop만 남기고, React 친화 타입(children: ReactNode 포함)은 HTMLAttributes 가 제공한다.
+    //
+    // `React.RefAttributes` 를 반드시 교집합에 넣는다 — `ForwardRefExoticComponent<P>` 는 P 에
+    // ref 를 자동으로 더해 주지 않는다. @lit/react 의 `ReactWebComponent` 자신이
+    // `PropsWithoutRef<…> & React.RefAttributes<I>` 로 선언돼 있으므로(런타임은 ref 를 전달한다),
+    // 이것을 빠뜨리면 **런타임은 되는데 타입만 거부하는** 괴리가 생긴다.
     const dts = `${dtsImports.join('\n')}
 
 export declare const ${className}: React.ForwardRefExoticComponent<
   Omit<Partial<${className}Element>, keyof React.HTMLAttributes<${className}Element>>
     & Omit<React.HTMLAttributes<${className}Element>, ${eventKeyUnion}>
+    & React.RefAttributes<${className}Element>
     & {
 ${eventTypes}  }
 >;

package/skills/iyulab-components/references/components/popover.md

@@ -45,9 +45,25 @@ Inherits all `UFloatingElement` properties (see [floating.md](../extensions/floa
 | `showDelay` | `number` | `0` | — | Open delay in ms |
 | `hideDelay` | `number` | `0` | — | Close delay in ms |
 | `trigger` | `'click'\|'contextmenu'\|'hover'\|'focus'\|'manual'` | `'click'` | ✓ | Open trigger |
-| `dismiss` | `string[]` | `['click','escape','scroll','resize']` | ✓ | Close triggers |
+| `dismiss` | `string[]` | `['click','escape','scroll','resize']` | ✓ | Close triggers — see note below |
 | `autofocus` | `boolean` | `false` | ✓ | Focus first focusable element on open |
 
+### `dismiss` semantics
+
+`click` and `escape` express user intent and always close the popover.
+
+`scroll` and `resize` are viewport-geometry changes and **only close the popover when it is
+anchored to a coordinate** — i.e. the virtual anchor created by `trigger="contextmenu"`, whose
+`clientX`/`clientY` stop matching whatever they pointed at once the page reflows.
+
+A popover anchored to a **real element** is not closed by scrolling or resizing: `autoUpdate`
+keeps it pinned to its anchor. If the anchor scrolls out of its clipping area entirely, the
+popover is *hidden* rather than closed (see `anchor-hidden` in
+[extensions/floating.md](../extensions/floating.md)) and returns when the anchor comes back.
+
+> Before 1.8.2 `scroll`/`resize` closed unconditionally, which contradicted `autoUpdate` and
+> collapsed open `u-select`/`u-input` listboxes on any page scroll.
+
 ## Events
 
 | Event | Cancelable | Description |

package/skills/iyulab-components/references/extensions/floating.md

@@ -45,6 +45,17 @@ export class MyDropdown extends UFloatingElement {
 | `showDelay` | `number` | `0` | — | Open delay (ms) |
 | `hideDelay` | `number` | `0` | — | Close delay (ms) |
 
+## Derived state
+
+| Attribute | Description |
+|-----------|-------------|
+| `anchor-hidden` | **Read-only — do not set.** Applied automatically while the anchor is fully outside its clipping area (scroll container or viewport). The element is hidden but **not closed** (`open` stays `true`) and returns as soon as the anchor is visible again. Available as a style hook: `my-dropdown[anchor-hidden] { … }` |
+
+This matters most with `strategy="fixed"`, which is used precisely so the floating element
+escapes `overflow` ancestor clipping — without `anchor-hidden` the panel would keep covering
+unrelated content after its anchor scrolled out of the panel. Backed by the `hide` middleware
+of `@floating-ui/dom`. Added in 1.8.2.
+
 ## Methods
 
 | Method | Returns | Description |