@iyulab/components 1.35.7 → 1.37.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [1.37.0] - 2026-09-06
+
+### Added
+
+- **`u-date-picker` and `u-select` expose a `:state(open)` custom state.**
+  Both already tracked their popover's open/closed state privately; it is now
+  surfaced through `ElementInternals.states` so consumers can style the trigger
+  while the popover is showing — `u-date-picker:state(open)::part(container)`,
+  `u-select:state(open)::part(container)`. Deliberately not a reflected
+  attribute: the state stays private to the component and exists only as a CSS
+  hook, so no new public attribute enters the API surface.
+
+### Documentation
+
+- **`UFloatingElement.placement` documents that `flip` is always applied.**
+  Whenever `placement` is set, floating-ui's `flip` middleware runs (switching
+  to the opposite side when the placed side has no room) — this has always been
+  the behavior but was undocumented, and `shift`'s description ("keeps the
+  element on screen") over-promised, since `shift` only corrects the cross axis
+  *within* a side. Both properties now describe the split, and a regression test
+  covers the flip fallback.
+
+## [1.36.0] - 2026-09-04
+
+### Added
+
+- **`UFileInput` (`u-file-input`), a form control wrapping a native
+  `<input type="file">`.** Trigger button, selected-file(s) status text,
+  and a clear button, styled to match the rest of the form control
+  family. `value` is `File[] | null`; native `<form>`/`u-form`
+  submission works out of the box via `ElementInternals` (single file)
+  or a `FormData` with the file repeatedly appended under the same key
+  (multiple files, matching native multi-file submission semantics).
+  `accept`/`multiple` pass through to the underlying input.
+  Drag-and-drop is out of scope for this release.
+
 ## [1.35.7] - 2026-09-03
 
 ### Fixed

package/README.md

@@ -70,7 +70,7 @@ npx skills add ./node_modules/@iyulab/components
 
 **Buttons & Actions** — `u-button`, `u-button-group`, `u-icon-button`, `u-copy-button`, `u-chip`
 
-**Form Controls** — `u-input`, `u-textarea`, `u-select`, `u-date-picker`, `u-checkbox`, `u-radio`, `u-switch`, `u-slider`, `u-rating`, `u-field`, `u-form`, `u-option`
+**Form Controls** — `u-input`, `u-textarea`, `u-select`, `u-date-picker`, `u-file-input`, `u-checkbox`, `u-radio`, `u-switch`, `u-slider`, `u-rating`, `u-field`, `u-form`, `u-option`
 
 **Overlay & Floating** — `u-dialog`, `u-drawer`, `u-popover`, `u-tooltip`
 

package/dist/assets/locales/ar.json.js

@@ -24,6 +24,9 @@ var nextMonth = "الشهر التالي";
 var close = "إغلاق";
 var copy = "نسخ";
 var copied = "تم النسخ";
+var chooseFile = "اختر ملفًا";
+var noFileChosen = "لم يتم اختيار أي ملف";
+var filesSelected = "تم اختيار {count} ملفات";
 var ar_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var ar_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, ar_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, ar_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/de.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Nächster Monat";
 var close = "Schließen";
 var copy = "Kopieren";
 var copied = "Kopiert";
+var chooseFile = "Datei auswählen";
+var noFileChosen = "Keine Datei ausgewählt";
+var filesSelected = "{count} Dateien ausgewählt";
 var de_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var de_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, de_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, de_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/en.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Next month";
 var close = "Close";
 var copy = "Copy";
 var copied = "Copied";
+var chooseFile = "Choose file";
+var noFileChosen = "No file chosen";
+var filesSelected = "{count} files selected";
 var en_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var en_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, en_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, en_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/es.json.js

@@ -23,6 +23,9 @@ var nextMonth = "Mes siguiente";
 var close = "Cerrar";
 var copy = "Copiar";
 var copied = "Copiado";
+var chooseFile = "Elegir archivo";
+var noFileChosen = "Ningún archivo elegido";
+var filesSelected = "{count} archivos seleccionados";
 var es_default = {
 	valueMissing,
 	badInput,
@@ -48,7 +51,10 @@ var es_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, es_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, es_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/fr.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Mois suivant";
 var close = "Fermer";
 var copy = "Copier";
 var copied = "Copié";
+var chooseFile = "Choisir un fichier";
+var noFileChosen = "Aucun fichier choisi";
+var filesSelected = "{count} fichiers sélectionnés";
 var fr_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var fr_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, fr_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, fr_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/id.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Bulan berikutnya";
 var close = "Tutup";
 var copy = "Salin";
 var copied = "Disalin";
+var chooseFile = "Pilih berkas";
+var noFileChosen = "Tidak ada berkas dipilih";
+var filesSelected = "{count} berkas dipilih";
 var id_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var id_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, id_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, id_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/ja.json.js

@@ -24,6 +24,9 @@ var nextMonth = "翌月";
 var close = "閉じる";
 var copy = "コピー";
 var copied = "コピーしました";
+var chooseFile = "ファイルを選択";
+var noFileChosen = "ファイルが選択されていません";
+var filesSelected = "{count}個のファイルを選択しました";
 var ja_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var ja_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, ja_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, ja_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/ko.json.js

@@ -24,6 +24,9 @@ var nextMonth = "다음 달";
 var close = "닫기";
 var copy = "복사";
 var copied = "복사됨";
+var chooseFile = "파일 선택";
+var noFileChosen = "선택된 파일 없음";
+var filesSelected = "{count}개 파일 선택됨";
 var ko_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var ko_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, ko_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, ko_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/pt-BR.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Próximo mês";
 var close = "Fechar";
 var copy = "Copiar";
 var copied = "Copiado";
+var chooseFile = "Escolher arquivo";
+var noFileChosen = "Nenhum arquivo escolhido";
+var filesSelected = "{count} arquivos selecionados";
 var pt_BR_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var pt_BR_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, pt_BR_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, pt_BR_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/ru.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Следующий месяц";
 var close = "Закрыть";
 var copy = "Копировать";
 var copied = "Скопировано";
+var chooseFile = "Выбрать файл";
+var noFileChosen = "Файл не выбран";
+var filesSelected = "Выбрано файлов: {count}";
 var ru_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var ru_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, ru_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, ru_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/th.json.js

@@ -24,6 +24,9 @@ var nextMonth = "เดือนถัดไป";
 var close = "ปิด";
 var copy = "คัดลอก";
 var copied = "คัดลอกแล้ว";
+var chooseFile = "เลือกไฟล์";
+var noFileChosen = "ยังไม่ได้เลือกไฟล์";
+var filesSelected = "เลือกแล้ว {count} ไฟล์";
 var th_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var th_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, th_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, th_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/vi.json.js

@@ -24,6 +24,9 @@ var nextMonth = "Tháng sau";
 var close = "Đóng";
 var copy = "Sao chép";
 var copied = "Đã sao chép";
+var chooseFile = "Chọn tệp";
+var noFileChosen = "Chưa chọn tệp nào";
+var filesSelected = "Đã chọn {count} tệp";
 var vi_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var vi_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, vi_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, vi_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/zh-CN.json.js

@@ -24,6 +24,9 @@ var nextMonth = "下个月";
 var close = "关闭";
 var copy = "复制";
 var copied = "已复制";
+var chooseFile = "选择文件";
+var noFileChosen = "未选择文件";
+var filesSelected = "已选择{count}个文件";
 var zh_CN_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var zh_CN_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, zh_CN_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, zh_CN_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/assets/locales/zh-TW.json.js

@@ -24,6 +24,9 @@ var nextMonth = "下個月";
 var close = "關閉";
 var copy = "複製";
 var copied = "已複製";
+var chooseFile = "選擇檔案";
+var noFileChosen = "未選擇檔案";
+var filesSelected = "已選擇{count}個檔案";
 var zh_TW_default = {
 	valueMissing,
 	badInput,
@@ -49,7 +52,10 @@ var zh_TW_default = {
 	nextMonth,
 	close,
 	copy,
-	copied
+	copied,
+	chooseFile,
+	noFileChosen,
+	filesSelected
 };
 //#endregion
-export { badInput, chooseDate, clear, close, copied, copy, decrement, zh_TW_default as default, goToSlide, hidePassword, increment, nextMonth, nextSlide, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };
+export { badInput, chooseDate, chooseFile, clear, close, copied, copy, decrement, zh_TW_default as default, filesSelected, goToSlide, hidePassword, increment, nextMonth, nextSlide, noFileChosen, patternMismatch, previousMonth, previousSlide, rangeOverflow, rangeUnderflow, showPassword, stepMismatch, time, today, tooLong, tooShort, typeMismatch, valueMissing };

package/dist/components/UFloatingElement.d.ts

@@ -51,6 +51,12 @@ export declare class UFloatingElement extends UElement {
      * 대상 엘리먼트로부터의 배치 위치입니다.
      * 지정하지 않으면 자동으로 가장 적절한 위치가 선택됩니다.
      *
+     * @remarks
+     * 지정한 변(side)에 공간이 없으면 반대 변으로 자동 전환됩니다(floating-ui의
+     * `flip` 미들웨어가 `placement`를 지정했을 때 항상 함께 적용됩니다 — 별도
+     * 옵션으로 끌 수 없습니다). `shift`는 이 전환과 별개로, 전환된(또는 지정된)
+     * 변 **안에서** 교차축 위치만 보정합니다.
+     *
      * @default undefined
      */
     placement?: Placement;
@@ -62,7 +68,9 @@ export declare class UFloatingElement extends UElement {
      */
     offset: OffsetOptions;
     /**
-     * 엘리먼트가 화면 안에 머물도록 자동으로 위치를 조정할지 여부입니다.
+     * 지정된(또는 `flip`으로 전환된) 배치 변 **안에서** 교차축 위치를 자동으로
+     * 보정할지 여부입니다 — 그 변 자체에 공간이 없어 반대 변으로 넘어가는 것은
+     * `placement` 설명의 `flip` 동작이 담당합니다.
      *
      * @default false
      */

package/dist/components/date-picker/UDatePicker.d.ts

@@ -16,6 +16,11 @@ export type DatePickerMode = 'date' | 'datetime';
  * first day of week from `Intl.Locale(locale).weekInfo?.firstDay`, falling back to Sunday
  * where unsupported.
  *
+ * Exposes a `:state(open)` custom state (via `ElementInternals.states`) while the calendar
+ * popover is showing — style with `u-date-picker:state(open)::part(container)`. Unlike
+ * `mode`/`clearable`, this state is never reflected as a public attribute — it exists purely
+ * as a CSS hook for consumers who want to react to the open/closed state from outside.
+ *
  * @csspart field - the u-field element
  * @csspart container - the element wrapping the trigger area
  * @csspart popover - the popover element showing the calendar

package/dist/components/date-picker/UDatePicker.js

@@ -178,6 +178,7 @@ var UDatePicker = class UDatePicker extends UFormControlElement {
 	updated(changed) {
 		super.updated(changed);
 		if (changed.has("value")) this.internals?.setFormValue(this.value ?? "");
+		if (changed.has("open")) this.internals?.states[this.open ? "add" : "delete"]("open");
 		if (changed.has("open") && this.open || changed.has("focusedDate") && this.open && this.grabFocusOnUpdate) {
 			this.grabFocusOnUpdate = false;
 			this.popoverEl?.updateComplete.then(() => this.focusDayButton(this.focusedDate));

package/dist/components/file-input/UFileInput.d.ts

@@ -0,0 +1,57 @@
+import { PropertyValues } from 'lit';
+import { UFormControlElement } from '../UFormControlElement.js';
+/**
+ * 파일 선택 입력 컴포넌트입니다. 네이티브 `<input type="file">`를 감싸
+ * 디자인시스템 톤의 트리거 버튼 + 선택 결과 표시로 렌더링합니다.
+ *
+ * 값은 항상 `File[] | null`입니다 — `multiple`이 꺼져 있어도 선택된 파일은
+ * 배열(0개 또는 1개)로 담깁니다. 폼 제출 시 파일이 1개면 그 `File`을,
+ * 여러 개면 같은 `name`으로 반복 append한 `FormData`를 `ElementInternals`에
+ * 전달합니다 — 네이티브 `<input type="file" multiple>`과 같은 제출 형태입니다.
+ *
+ * @csspart field - u-field 요소
+ * @csspart container - 트리거·상태 텍스트·지우기 버튼을 감싸는 컨테이너
+ * @csspart trigger - 파일 선택 트리거 버튼
+ * @csspart status - 선택 상태 텍스트("선택된 파일 없음" · 파일명 · "N개 파일 선택됨")
+ * @csspart clear-button - 선택 해제 버튼(u-icon)
+ * @csspart input - 숨겨진 네이티브 `<input type="file">`
+ *
+ * @cssprop --u-file-input-display - 호스트의 display (기본값: inline-block)
+ * @cssprop --u-file-input-width - 호스트의 width (기본값: auto)
+ *
+ * @event change - 선택된 파일이 바뀔 때 발생(선택·지우기 공통)
+ */
+export declare class UFileInput extends UFormControlElement<File[] | null> {
+    static styles: import('lit').CSSResultGroup[];
+    /** 값은 attribute로 표현될 수 없다 — 항상 프로그램적으로만 설정된다. */
+    value: File[] | null;
+    /** 선택 가능한 파일 형식을 제한한다(네이티브 `accept` 속성 그대로 통과). */
+    accept?: string;
+    /** 여러 파일을 한 번에 선택할 수 있는지 여부. */
+    multiple: boolean;
+    triggerEl?: HTMLButtonElement;
+    inputEl?: HTMLInputElement;
+    /** `value`가 바뀌는 모든 경로(선택·지우기)에서 폼 제출값을 동기화한다 —
+     *  `UInput`/`UCheckbox`와 같은 경계(`DL-289-1`). 파일은 문자열로 표현할 수
+     *  없으므로 1개면 `File`을, 여러 개면 같은 키로 반복 append한 `FormData`를
+     *  넘긴다 — 네이티브 `<input type="file" multiple>`의 제출 형태와 동일하다. */
+    protected updated(changedProperties: PropertyValues): void;
+    private syncFormValue;
+    render(): import('lit-html').TemplateResult<1>;
+    protected setValidity(): void;
+    reset(): void;
+    focus(options?: FocusOptions): void;
+    blur(): void;
+    private handleTriggerClick;
+    private handleInputChange;
+    private handleClearButtonClick;
+    /** `clear-btn`은 순수 표시 요소(`u-icon`)라 네이티브 키보드 활성화가 없다 —
+     *  `role="button"`+`tabindex="0"`로 포커스 가능하게 한 뒤, Enter/Space를 같은
+     *  클릭 핸들러로 릴레이한다(`UInput.handleSuffixIconKeydown`과 같은 패턴). */
+    private handleClearButtonKeydown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-file-input': UFileInput;
+    }
+}

package/dist/components/file-input/UFileInput.js

@@ -0,0 +1,140 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import { UFormControlElement } from "../UFormControlElement.js";
+import "../icon/UIcon.js";
+import { Locale } from "../../utilities/Locale.js";
+import "../field/UField.js";
+import { styles } from "./UFileInput.styles.js";
+import { html } from "lit";
+import { customElement, property, query } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+//#region src/components/file-input/UFileInput.ts
+var UFileInput = class UFileInput extends UFormControlElement {
+	constructor(..._args) {
+		super(..._args);
+		this.value = null;
+		this.multiple = false;
+		this.handleTriggerClick = (e) => {
+			e.stopImmediatePropagation();
+			if (this.disabled || this.readonly) return;
+			this.inputEl?.click();
+		};
+		this.handleInputChange = (e) => {
+			const input = e.target;
+			this.value = input.files && input.files.length > 0 ? Array.from(input.files) : null;
+			if (!this.novalidate) this.validate();
+			this.relay(e);
+		};
+		this.handleClearButtonClick = (e) => {
+			e.stopImmediatePropagation();
+			this.reset();
+			this.dispatchEvent(new InputEvent("input", {
+				bubbles: true,
+				composed: true
+			}));
+			this.dispatchEvent(new Event("change", {
+				bubbles: true,
+				composed: true
+			}));
+			this.focus();
+		};
+		this.handleClearButtonKeydown = (e) => {
+			if (e.key !== "Enter" && e.key !== " ") return;
+			e.preventDefault();
+			this.handleClearButtonClick(e);
+		};
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	/** `value`가 바뀌는 모든 경로(선택·지우기)에서 폼 제출값을 동기화한다 —
+	*  `UInput`/`UCheckbox`와 같은 경계(`DL-289-1`). 파일은 문자열로 표현할 수
+	*  없으므로 1개면 `File`을, 여러 개면 같은 키로 반복 append한 `FormData`를
+	*  넘긴다 — 네이티브 `<input type="file" multiple>`의 제출 형태와 동일하다. */
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		if (changedProperties.has("value")) this.syncFormValue();
+	}
+	syncFormValue() {
+		const files = this.value ?? [];
+		if (files.length === 0) this.internals?.setFormValue(null);
+		else if (files.length === 1) this.internals?.setFormValue(files[0]);
+		else {
+			const fd = new FormData();
+			for (const file of files) fd.append(this.name ?? "", file);
+			this.internals?.setFormValue(fd);
+		}
+	}
+	render() {
+		const files = this.value ?? [];
+		const hasFiles = files.length > 0;
+		const status = !hasFiles ? Locale.getValue("noFileChosen") : files.length === 1 ? files[0].name : Locale.getValue("filesSelected", { count: files.length });
+		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">
+          <button class="trigger" part="trigger"
+            type="button"
+            ?disabled=${this.disabled || this.readonly}
+            @click=${this.handleTriggerClick}
+          >${Locale.getValue("chooseFile")}</button>
+
+          <span class="status" part="status" ?data-empty=${!hasFiles}>${status}</span>
+
+          <u-icon class="clear-btn" part="clear-button"
+            ?hidden=${!hasFiles || this.disabled || this.readonly}
+            role="button"
+            tabindex="0"
+            aria-label=${Locale.getValue("clear")}
+            lib="internal"
+            name="x"
+            @click=${this.handleClearButtonClick}
+            @keydown=${this.handleClearButtonKeydown}
+          ></u-icon>
+
+          <input class="native-input" part="input"
+            type="file"
+            hidden
+            name=${ifDefined(this.name)}
+            accept=${ifDefined(this.accept)}
+            ?multiple=${this.multiple}
+            ?disabled=${this.disabled || this.readonly}
+            @change=${this.handleInputChange}
+          />
+        </div>
+      </u-field>
+    `;
+	}
+	setValidity() {
+		const missing = this.required && (!this.value || this.value.length === 0);
+		this.commit(missing ? { valueMissing: true } : {}, missing ? Locale.getValue("valueMissing") : "", this.triggerEl ?? void 0);
+	}
+	reset() {
+		this.value = null;
+		this.invalid = false;
+		if (this.inputEl) this.inputEl.value = "";
+	}
+	focus(options) {
+		this.triggerEl?.focus(options);
+	}
+	blur() {
+		this.triggerEl?.blur();
+	}
+};
+__decorate([property({ attribute: false }), __decorateMetadata("design:type", Object)], UFileInput.prototype, "value", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFileInput.prototype, "accept", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFileInput.prototype, "multiple", void 0);
+__decorate([query(".trigger", true), __decorateMetadata("design:type", typeof HTMLButtonElement === "undefined" ? Object : HTMLButtonElement)], UFileInput.prototype, "triggerEl", void 0);
+__decorate([query("input[type=\"file\"]", true), __decorateMetadata("design:type", typeof HTMLInputElement === "undefined" ? Object : HTMLInputElement)], UFileInput.prototype, "inputEl", void 0);
+UFileInput = __decorate([customElement("u-file-input")], UFileInput);
+//#endregion
+export { UFileInput };

package/dist/components/file-input/UFileInput.styles.d.ts

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

package/dist/components/file-input/UFileInput.styles.js

@@ -0,0 +1,80 @@
+import { css } from "lit";
+//#region src/components/file-input/UFileInput.styles.ts
+var styles = css`
+  :host {
+    display: var(--u-file-input-display, inline-block);
+    width: var(--u-file-input-width, auto);
+    color: var(--u-txt-color, #212121);
+    font-size: inherit;
+    font-family: var(--u-font-base);
+  }
+
+  .container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.6em;
+  }
+
+  .trigger {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    padding: 0.4em 0.9em;
+    border: 1px solid var(--u-input-border-color, #E0E0E0);
+    border-radius: 0.25em;
+    background-color: var(--u-panel-bg-color, #FFFFFF);
+    color: var(--u-primary-color, #1976D2);
+    font: inherit;
+    font-weight: 500;
+    cursor: pointer;
+    transition: border-color var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1)), background-color var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1));
+  }
+  .trigger:hover:not(:disabled) {
+    background-color: var(--u-neutral-100, #F5F5F5);
+    border-color: var(--u-input-border-color-hover, #BDBDBD);
+  }
+  .trigger:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 1px var(--u-input-border-color-focus, #1565C0),
+      0 0 0 3px color-mix(in srgb, var(--u-primary-color-strong, #1565C0) 22%, transparent);
+  }
+  .trigger:disabled {
+    color: var(--u-txt-color-weak, #757575);
+    background-color: var(--u-bg-color-disabled, #FAFAFA);
+    border-color: var(--u-border-color-weak, #EEEEEE);
+    cursor: not-allowed;
+  }
+
+  .status {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 0.9em;
+  }
+  .status[data-empty] {
+    color: var(--u-txt-color-weak, #757575);
+  }
+
+  .clear-btn {
+    flex-shrink: 0;
+    color: var(--u-icon-color, #616161);
+    font-size: 1em;
+    cursor: pointer;
+    transition: color var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1));
+  }
+  .clear-btn:hover {
+    color: var(--u-icon-color-hover, #1565C0);
+  }
+  .clear-btn:active {
+    color: var(--u-icon-color-active, #1565C0);
+  }
+
+  :host([invalid]) .trigger {
+    border-color: var(--u-input-border-color-invalid, #C62828);
+  }
+`;
+//#endregion
+export { styles };

package/dist/components/select/USelect.d.ts

@@ -12,6 +12,10 @@ export type SelectVariant = 'outlined' | 'filled' | 'underlined' | 'borderless';
  *   팝오버 목록에서 사라지기 때문. 리치 콘텐츠가 필요하면 이 slot에 별도 마크업을 할당하고
  *   `change` 이벤트에서 직접 갱신한다.)
  *
+ * 옵션 목록 팝오버가 열려 있는 동안 `:state(open)` 커스텀 상태를 노출한다(via
+ * `ElementInternals.states`) — `u-select:state(open)::part(container)`로 스타일링할 수
+ * 있다. 공개 속성으로 반사되지 않는다.
+ *
  * @csspart field - u-field 요소
  * @csspart container - 트리거 영역을 감싸는 요소
  * @csspart popover - 옵션 목록이 표시되는 팝오버 요소

package/dist/components/select/USelect.js

@@ -153,6 +153,7 @@ var USelect = class USelect extends UFormControlElement {
 	updated(changedProperties) {
 		super.updated(changedProperties);
 		if (["value", "options"].some((k) => changedProperties.has(k))) this.onChangeValue();
+		if (changedProperties.has("open")) this.internals?.states[this.open ? "add" : "delete"]("open");
 	}
 	render() {
 		return html`

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * from './components/divider/UDivider.js';
 export * from './components/drawer/UDrawer.js';
 export * from './components/expander/UExpander.js';
 export * from './components/field/UField.js';
+export * from './components/file-input/UFileInput.js';
 export * from './components/form/UForm.js';
 export * from './components/icon/UIcon.js';
 export * from './components/icon-button/UIconButton.js';

package/dist/index.js

@@ -32,6 +32,7 @@ import { UDialog } from "./components/dialog/UDialog.js";
 import { UDivider } from "./components/divider/UDivider.js";
 import { UDrawer } from "./components/drawer/UDrawer.js";
 import { UExpander } from "./components/expander/UExpander.js";
+import { UFileInput } from "./components/file-input/UFileInput.js";
 import { UForm } from "./components/form/UForm.js";
 import { UOption } from "./components/option/UOption.js";
 import { UInput } from "./components/input/UInput.js";
@@ -57,4 +58,4 @@ import { BrowserStorage } from "./utilities/BrowserStorage.js";
 import { Dialog } from "./utilities/Dialog.js";
 import { Theme } from "./utilities/Theme.js";
 import { Toast } from "./utilities/Toast.js";
-export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDatePicker, UDialog, UDivider, UDrawer, UElement, UExpander, UField, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UText, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, formatCurrency, formatDate, formatNumber, getDefaultBaseUrl, getParentElement, isCoarsePointer, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };
+export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDatePicker, UDialog, UDivider, UDrawer, UElement, UExpander, UField, UFileInput, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UText, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, formatCurrency, formatDate, formatNumber, getDefaultBaseUrl, getParentElement, isCoarsePointer, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };

package/dist/react/UFileInput.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { UFileInput as UFileInputElement } from '../components/file-input/UFileInput';
+
+export declare const UFileInput: React.ForwardRefExoticComponent<
+  Omit<Partial<UFileInputElement>, keyof React.HTMLAttributes<UFileInputElement>>
+    & Omit<React.HTMLAttributes<UFileInputElement>, 'onChange'>
+    & React.RefAttributes<UFileInputElement>
+    & {
+  onChange?: (event: CustomEvent) => void;
+  }
+>;
+
+export type UFileInputProps = React.ComponentProps<typeof UFileInput>;

package/dist/react/UFileInput.js

@@ -0,0 +1,12 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UFileInput as UFileInputElement } from '../components/file-input/UFileInput.js';
+
+export const UFileInput = createComponent({
+  react: React,
+  tagName: 'u-file-input',
+  elementClass: UFileInputElement,
+  events: {
+    onChange: 'change',
+  },
+});

package/dist/react/index.d.ts

@@ -25,6 +25,7 @@ export { UInput, UInputProps } from './UInput';
 export { UIconButton, UIconButtonProps } from './UIconButton';
 export { UIcon, UIconProps } from './UIcon';
 export { UForm, UFormProps } from './UForm';
+export { UFileInput, UFileInputProps } from './UFileInput';
 export { UField, UFieldProps } from './UField';
 export { UExpander, UExpanderProps } from './UExpander';
 export { UDrawer, UDrawerProps } from './UDrawer';

package/dist/react/index.js

@@ -25,6 +25,7 @@ export { UInput } from './UInput.js';
 export { UIconButton } from './UIconButton.js';
 export { UIcon } from './UIcon.js';
 export { UForm } from './UForm.js';
+export { UFileInput } from './UFileInput.js';
 export { UField } from './UField.js';
 export { UExpander } from './UExpander.js';
 export { UDrawer } from './UDrawer.js';

package/dist/utilities/Locale.d.ts

@@ -12,7 +12,7 @@ export type SupportedLocale = 'en' | 'ko' | 'ja' | 'zh-CN' | 'zh-TW' | 'es' | 'f
 /** 내장 로케일은 자동완성되지만, 임의의 BCP47 태그도 그대로 받는다. */
 export type LocaleTag = SupportedLocale | (string & {});
 /** 라이브러리가 제공하는 chrome 문자열 키. 지금은 검증 메시지뿐이지만 이후 다른 UI 문구도 추가될 수 있다. */
-export type LocaleMessageKey = 'valueMissing' | 'badInput' | 'typeMismatch' | 'patternMismatch' | 'rangeUnderflow' | 'rangeOverflow' | 'stepMismatch' | 'tooShort' | 'tooLong' | 'increment' | 'decrement' | 'clear' | 'today' | 'time' | 'showPassword' | 'hidePassword' | 'previousSlide' | 'nextSlide' | 'goToSlide' | 'chooseDate' | 'previousMonth' | 'nextMonth' | 'close' | 'copy' | 'copied';
+export type LocaleMessageKey = 'valueMissing' | 'badInput' | 'typeMismatch' | 'patternMismatch' | 'rangeUnderflow' | 'rangeOverflow' | 'stepMismatch' | 'tooShort' | 'tooLong' | 'increment' | 'decrement' | 'clear' | 'today' | 'time' | 'showPassword' | 'hidePassword' | 'previousSlide' | 'nextSlide' | 'goToSlide' | 'chooseDate' | 'previousMonth' | 'nextMonth' | 'close' | 'copy' | 'copied' | 'chooseFile' | 'noFileChosen' | 'filesSelected';
 type LocaleTable = Record<LocaleMessageKey, string>;
 /**
  * 한 패키지(또는 앱 영역)의 문자열 묶음.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.35.7",
+  "version": "1.37.0",
   "keywords": [
     "iyulab",
     "components",

package/skills/iyulab-components/SKILL.md

@@ -67,6 +67,8 @@ import { UButton, UInput } from '@iyulab/components/react';
 - [`u-input`](./references/components/input.md) — Text input; combobox mode when `u-option` children are present
 - [`u-textarea`](./references/components/textarea.md) — Multi-line text input with auto-resize and character counter
 - [`u-select`](./references/components/select.md) — Dropdown select; single or multiple, with search
+- [`u-date-picker`](./references/components/date-picker.md) — Single-date(-time) selection with a popover calendar
+- [`u-file-input`](./references/components/file-input.md) — File picker with a design-system trigger button and selected-file(s) display
 - [`u-checkbox`](./references/components/checkbox.md) — Checkbox with indeterminate state support
 - [`u-radio`](./references/components/radio.md) — Radio group built from `u-option` children
 - [`u-switch`](./references/components/switch.md) — Toggle switch

package/skills/iyulab-components/references/components/file-input.md

@@ -0,0 +1,81 @@
+# u-file-input
+
+```ts
+import '@iyulab/components/dist/components/file-input/UFileInput.js';
+```
+
+**Tag:** `u-file-input`
+
+File picker with a design-system-styled trigger button and a selected-file(s) status display,
+wrapping a hidden native `<input type="file">`. Form-associated (`formAssociated = true`).
+
+`value` is always `File[] | null` — even with `multiple` off, a selected file is held as a
+one-element array. On form submission: 0 files → nothing is sent for `name`; 1 file → the `File`
+itself; more than 1 file → a `FormData` with the same `File` repeatedly appended under `name`,
+matching what a native `<input type="file" multiple>` submits.
+
+```html
+<u-file-input name="attachment" required accept="image/*"></u-file-input>
+
+<u-file-input name="attachments" multiple accept=".csv,.xlsx"></u-file-input>
+```
+
+```ts
+const picker = document.querySelector('u-file-input');
+picker.addEventListener('change', () => {
+  console.log(picker.value); // File[] | null
+});
+```
+
+No drag-and-drop in this version — it is a minimal wrapper (trigger + status + clear), by design.
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `File[] \| null` | `null` | — | Selected files (always an array, even for single-file selection) |
+| `accept` | `string` | — | — | Passed through to the native `accept` attribute |
+| `multiple` | `boolean` | `false` | ✓ | Allow selecting more than one file |
+| `disabled` | `boolean` | `false` | ✓ | Disable the control |
+| `readonly` | `boolean` | `false` | ✓ | Read-only (trigger and clear button inert) |
+| `required` | `boolean` | `false` | ✓ | Required field |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed state |
+| `name` | `string` | — | — | Form field name |
+| `label` | `string` | — | — | Label text |
+| `description` | `string` | — | — | Helper text below the control |
+| `validationMessage` | `string` | — | — | Custom validation message |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `validate()` | `boolean` | Run validation; sets `invalid` |
+| `reset()` | `void` | Clear the selection and validation state |
+| `focus(options?)` | `void` | Focus the trigger button |
+| `blur()` | `void` | Blur the trigger button |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `field` | Inner `u-field` element (label/description/validation layout) |
+| `container` | Wrapper around the trigger, status text, and clear button |
+| `trigger` | The file-picker trigger button |
+| `status` | Status text — "No file chosen", the filename, or "N files selected" |
+| `clear-button` | Clear-selection button (a `u-icon`) |
+| `input` | The hidden native `<input type="file">` |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|--------------|
+| `--u-file-input-display` | Host `display` (default: `inline-block`) |
+| `--u-file-input-width` | Host `width` (default: `auto`) |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when the selection changes (picking files or clearing) |

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

@@ -40,7 +40,7 @@ Inherits all `UFloatingElement` properties (see [floating.md](../extensions/floa
 | `disabled` | `boolean` | `false` | ✓ | Disable opening |
 | `placement` | `Placement` | — | — | Preferred placement (`top`, `bottom`, `left`, `right`, `*-start`, `*-end`) |
 | `offset` | `OffsetOptions` | `0` | — | Distance from anchor |
-| `shift` | `boolean` | `false` | — | Auto-shift to stay in viewport |
+| `shift` | `boolean` | `false` | — | Correct the cross-axis position *within* the placed side (see note below) |
 | `arrow` | `boolean` | `false` | — | Show arrow pointing to anchor |
 | `showDelay` | `number` | `0` | — | Open delay in ms |
 | `hideDelay` | `number` | `0` | — | Close delay in ms |
@@ -48,6 +48,12 @@ Inherits all `UFloatingElement` properties (see [floating.md](../extensions/floa
 | `dismiss` | `string[]` | `['click','escape','scroll','resize']` | ✓ | Close triggers — see note below |
 | `autofocus` | `boolean` | `false` | ✓ | Focus first focusable element on open |
 
+> **Placement fallback**: whenever `placement` is set, floating-ui's `flip` middleware is
+> always applied — if the placed side has no room, the element switches to the opposite side.
+> `shift` is a separate, narrower correction: it nudges the element along the cross axis
+> *within* whichever side ended up being used. Neither can be turned off independently.
+
+
 ### `dismiss` semantics
 
 `click` and `escape` express user intent and always close the popover.

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

@@ -43,13 +43,19 @@ Inherits all `UFloatingElement` properties (see [floating.md](../extensions/floa
 | `open` | `boolean` | `false` | ✓ | Visibility state |
 | `placement` | `Placement` | — | — | Preferred placement |
 | `offset` | `OffsetOptions` | `0` | — | Gap from target |
-| `shift` | `boolean` | `false` | — | Auto-shift to stay in viewport |
+| `shift` | `boolean` | `false` | — | Correct the cross-axis position *within* the placed side (see note below) |
 | `arrow` | `boolean` | `false` | — | Show pointing arrow |
 | `showDelay` | `number` | `0` | — | Open delay in ms |
 | `hideDelay` | `number` | `0` | — | Close delay in ms |
 | `interactive` | `boolean` | `false` | ✓ | Keep open when mouse is over tooltip |
 | `tracking` | `boolean` | `false` | ✓ | Follow mouse cursor position |
 
+> **Placement fallback**: whenever `placement` is set, floating-ui's `flip` middleware is
+> always applied — if the placed side has no room, the element switches to the opposite side.
+> `shift` is a separate, narrower correction: it nudges the element along the cross axis
+> *within* whichever side ended up being used. Neither can be turned off independently.
+
+
 ## Events
 
 | Event | Cancelable | Description |