@iyulab/components 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.7.0] - 2026-07-17
+
+### Fixed
+- **폼 컨트롤 `change` 이벤트 의미론을 네이티브 규약으로 교정** — `USelect`/`URadio`/`URating`/`USlider`가 `updated()` 경로에서 무조건 `change`를 발화해, (1) 옵션 slot 등록 시 `value===undefined` 상태의 change가 발화되어 React 등 controlled 래퍼의 state를 오염시키고(옵션 등록 전 세팅한 초기값이 유실·서버 enum 기본값으로 저장되는 무증상 데이터 결함 — yesung 실측), (2) 프로그램적 `value` 세팅이 사용자 이벤트로 위장되어 에코 루프를 만들던 문제 수정. 이제 `change`는 **사용자 상호작용**(옵션 클릭·키보드·칩 제거·지우기·드래그 확정)에서만 발화한다(ISSUE-components-20260717-uselect-value-before-options). `UInput`(blur 발화)·`UMenu`/`UTree`(핸들러 발화)는 원래 규약대로였으며 변경 없음.
+- `USlider`: 문서("드래그 완료 후 발생")와 달리 **드래그 중 매 pointermove마다 change가 연사**되던 결함 수정 — 이제 `pointerup` 시 값이 실제로 바뀐 경우 1회 발화. 단일 select에서 동일 옵션 재선택, 선택된 라디오 재클릭도 네이티브와 동일하게 미발화.
+- `USelect`/`URadio`/`URating`의 `onChangeValue()`가 `updated()` 내부에서 `validate()`→`requestUpdate()`를 호출해 v1.5.1 검증 아키텍처를 위반하고 "scheduled an update after an update completed" Lit 경고를 재유발하던 잔재 제거 — 검증 UI 갱신(`validate()`)은 사용자 상호작용 경로에서만 수행하고, 프로그램적 세팅은 base의 silent `setValidity()`로 internals만 갱신한다.
+- **마크업 `value` attribute 선언이 일반 문자열에서 silently null이 되던 갭 수정** — base가 `type: Object`(JSON.parse)여서 `<u-input value="hello">`·`<u-select value="b">`가 null로 해석됐다. 기본 해석을 raw 문자열로 바꾸고, `u-rating`/`u-slider`는 숫자, `u-select`(multiple)/`u-slider`(range)는 JSON 배열(`value='["a","b"]'`)을 지원한다.
+- `USlider` range 표시 텍스트의 구분자 인코딩 오염(`5 ??10`) → `5 ~ 10`으로 교정. `URating` min/max 주석 모지바케 정리.
+
+### Changed
+- 프로그램적 `value` 세팅은 이제 `change` 발화·`invalid` 플래그 자동 갱신을 하지 않는다(`ElementInternals` validity는 계속 동기화됨). 프로그램적 변경 후 검증 UI 갱신이 필요하면 `validate()`를 명시 호출할 것. `value='"quoted"'` 형태(JSON 문자열)로 attribute를 우회 선언하던 경우 이제 따옴표 포함 raw 문자열로 해석된다.
+
 ## [1.6.0] - 2026-07-16
 
 ### Added

package/dist/components/UFormControlElement.d.ts

@@ -23,7 +23,9 @@ export declare abstract class UFormControlElement<T> extends UElement {
     description?: string;
     /** 폼 제출 시 사용되는 이름 */
     name?: string;
-    /** 폼 제출 시 사용되는 값 */
+    /** 폼 제출 시 사용되는 값. attribute 선언 시 기본은 raw 문자열로 해석한다 —
+     *  (이전의 type: Object는 JSON.parse 실패로 일반 문자열 attribute가 silently null이 되는 갭이 있었다)
+     *  string이 아닌 값 타입을 갖는 컨트롤(URating/USlider/USelect multiple)은 자신의 converter로 override한다. */
     value?: T;
     /**
      * ElementInternals는 폼과의 연동, 유효성 검사 상태 관리 등을 지원하는 네이티브 API입니다.

package/dist/components/UFormControlElement.js

@@ -116,6 +116,6 @@ __decorate([property({ type: Boolean }), __decorateMetadata("design:type", Boole
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFormControlElement.prototype, "label", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFormControlElement.prototype, "description", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFormControlElement.prototype, "name", void 0);
-__decorate([property({ type: Object }), __decorateMetadata("design:type", Object)], UFormControlElement.prototype, "value", void 0);
+__decorate([property(), __decorateMetadata("design:type", Object)], UFormControlElement.prototype, "value", void 0);
 //#endregion
 export { UFormControlElement };

package/dist/components/input/UInput.d.ts

@@ -16,7 +16,11 @@ export type InputVariant = 'outlined' | 'filled' | 'underlined' | 'borderless';
  *
  * @csspart field - u-field 요소
  * @csspart container - input과 prefix/suffix를 감싸는 컨테이너
- * @csspart input - 네이티브 input 요소
+ * @csspart input - 네이티브 input 요소.
+ *   text-align 등 표현 관련 속성을 지정하지 않으므로 소비앱이 ::part(input)으로 재정의한다.
+ *   예: `u-input[type="number"]::part(input) { text-align: right; font-variant-numeric: tabular-nums; }`
+ *   (숫자 우측정렬은 값이 열로 쌓여 자릿수를 비교할 때 유효하므로 라이브러리 기본값으로 두지 않는다.
+ *    docs/theming.md 참고)
  * @csspart popover - 드롭다운 팝오버 요소
  *
  * @cssprop --input-popover-width - 드롭다운 팝오버의 너비 (기본값: 앵커(트리거) 너비)
@@ -32,7 +36,7 @@ export declare class UInput extends UFormControlElement<string> {
     variant: InputVariant;
     /** 전체 지우기 버튼 표시 여부 */
     clearable: boolean;
-    /** input 요소의 type 속성 */
+    /** input 요소의 type 속성. 외부 `u-input[type="..."]` 스타일 훅을 위해 reflect 한다 (URadio.type 과 동일). */
     type: InputType;
     /** 최소 글자 수 */
     minlength?: number;

package/dist/components/input/UInput.js

@@ -276,7 +276,10 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Boolean)], UInput.prototype, "clearable", void 0);
-__decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UInput.prototype, "type", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UInput.prototype, "type", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], UInput.prototype, "minlength", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], UInput.prototype, "maxlength", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UInput.prototype, "min", void 0);

package/dist/components/radio/URadio.d.ts

@@ -11,7 +11,8 @@ export type RadioOrientation = "vertical" | "horizontal";
  * @csspart field - u-field 요소
  * @csspart container - 옵션들을 감싸는 컨테이너
  *
- * @event change - 선택 값이 변경될 때 발생
+ * @event change - 사용자 상호작용(옵션 클릭·키보드)으로 선택 값이 변경될 때 발생.
+ *   네이티브 라디오와 동일하게 프로그램적 value 세팅·옵션 등록으로는 발화하지 않는다.
  */
 export declare class URadio extends UFormControlElement<string> {
     static styles: import('lit').CSSResultGroup[];
@@ -30,6 +31,11 @@ export declare class URadio extends UFormControlElement<string> {
     private setup;
     private cleanup;
     private onChangeValue;
+    /** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+     *  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+     *  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+     *  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+    private emitChange;
     private handleSlotChange;
     private handleOptionClick;
     private handleOptionKeyDown;

package/dist/components/radio/URadio.js

@@ -25,7 +25,9 @@ var URadio = class URadio extends UFormControlElement {
 			if (this.readonly || this.disabled) return;
 			const option = e.currentTarget;
 			if (option.disabled) return;
+			if (option.value === this.value) return;
 			this.value = option.value;
+			this.emitChange();
 		};
 		this.handleOptionKeyDown = (e) => {
 			if (this.readonly || this.disabled) return;
@@ -125,6 +127,12 @@ var URadio = class URadio extends UFormControlElement {
 			option.selected = option.value === this.value;
 		});
 		this.internals?.setFormValue(this.value || "");
+	}
+	/** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+	*  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+	*  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+	*  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+	emitChange() {
 		if (!this.novalidate) this.validate();
 		this.dispatchEvent(new Event("change", {
 			bubbles: true,

package/dist/components/rating/URating.d.ts

@@ -14,16 +14,19 @@ import { UFormControlElement } from '../UFormControlElement.js';
  * @cssprop --rating-symbol-color - 활성화된 심볼 색상
  * @cssprop --rating-symbol-off-color - 비활성화된 심볼 색상
  *
- * @event change - 레이팅 값 변경 시 발생
+ * @event change - 사용자 상호작용(심볼 클릭·키보드)으로 레이팅 값이 변경될 때 발생.
+ *   프로그램적 value 세팅으로는 발화하지 않는다.
  */
 export declare class URating extends UFormControlElement<number> {
     static styles: import('lit').CSSResultGroup[];
-    /** 理쒖냼 媛?*/
+    /** 최소 값 */
     min: number;
-    /** 理쒕? 媛?*/
+    /** 최대 값 */
     max: number;
     /** 정밀도 (0.5 등) */
     precision: number;
+    /** 레이팅 값. attribute 선언 시 숫자로 해석한다. */
+    value?: number;
     private buffer;
     private symbol;
     private symbolOff;
@@ -35,6 +38,11 @@ export declare class URating extends UFormControlElement<number> {
     private isStepMismatch;
     reset(): void;
     private onChangeValue;
+    /** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+     *  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+     *  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+     *  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+    private emitChange;
     private handleSlotChange;
     private handleSymbolPointerMove;
     private handleSymbolPointerLeave;

package/dist/components/rating/URating.js

@@ -37,7 +37,10 @@ var URating = class URating extends UFormControlElement {
 			if (this.disabled || this.readonly) return;
 			const score = Number(e.currentTarget.dataset.score);
 			const val = this.precision < 1 ? this.calibrate(e, score) : score;
-			this.value = this.value === val ? 0 : val;
+			const next = this.value === val ? 0 : val;
+			if (next === this.value) return;
+			this.value = next;
+			this.emitChange();
 		};
 		this.handleSymbolKeydown = (e) => {
 			if (this.disabled || this.readonly) return;
@@ -68,7 +71,11 @@ var URating = class URating extends UFormControlElement {
 				case "Enter": {
 					e.preventDefault();
 					const score = Number(e.currentTarget.dataset.score);
-					this.value = this.value === score ? 0 : score;
+					const next = this.value === score ? 0 : score;
+					if (next !== this.value) {
+						this.value = next;
+						this.emitChange();
+					}
 					return;
 				}
 				default: return;
@@ -166,6 +173,12 @@ var URating = class URating extends UFormControlElement {
 	onChangeValue() {
 		this.buffer = -1;
 		this.internals?.setFormValue(this.value?.toString() || "");
+	}
+	/** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+	*  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+	*  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+	*  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+	emitChange() {
 		if (!this.novalidate) this.validate();
 		this.dispatchEvent(new Event("change", {
 			bubbles: true,
@@ -183,6 +196,7 @@ var URating = class URating extends UFormControlElement {
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Object)], URating.prototype, "min", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Object)], URating.prototype, "max", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Object)], URating.prototype, "precision", void 0);
+__decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], URating.prototype, "value", void 0);
 __decorate([state(), __decorateMetadata("design:type", Object)], URating.prototype, "buffer", void 0);
 __decorate([state(), __decorateMetadata("design:type", Object)], URating.prototype, "symbol", void 0);
 __decorate([state(), __decorateMetadata("design:type", Object)], URating.prototype, "symbolOff", void 0);

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

@@ -22,7 +22,8 @@ export type SelectVariant = 'outlined' | 'filled' | 'underlined' | 'borderless';
  * @cssprop --select-popover-min-height - 팝오버의 최소 높이 (기본값: 0px)
  * @cssprop --select-popover-max-height - 팝오버의 최대 높이 (기본값: 50vh)
  *
- * @event change - 선택 값이 변경될 때 발생
+ * @event change - 사용자 상호작용(옵션 클릭·칩 제거·지우기)으로 선택 값이 변경될 때 발생.
+ *   네이티브 select와 동일하게 프로그램적 value 세팅·옵션 등록으로는 발화하지 않는다.
  */
 export declare class USelect extends UFormControlElement<string | string[]> {
     static styles: import('lit').CSSResultGroup[];
@@ -42,6 +43,8 @@ export declare class USelect extends UFormControlElement<string | string[]> {
     maxCount?: number;
     /** placeholder 텍스트 */
     placeholder?: string;
+    /** 폼 제출 시 사용되는 값. attribute로는 단일 값 문자열 또는 JSON 배열(`value='["a","b"]'`)을 지원한다. */
+    value?: string | string[];
     containerEl?: HTMLElement;
     popoverEl?: UPopover;
     private options;
@@ -58,6 +61,11 @@ export declare class USelect extends UFormControlElement<string | string[]> {
     private setup;
     private cleanup;
     private onChangeValue;
+    /** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+     *  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+     *  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+     *  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+    private emitChange;
     private handleSlotChange;
     private handleOptionClick;
     private handleOptionKeydown;

package/dist/components/select/USelect.js

@@ -36,8 +36,11 @@ var USelect = class USelect extends UFormControlElement {
 					if (this.maxCount != null && values.length >= this.maxCount) return;
 					this.value = [...values, option.value];
 				}
+				this.emitChange();
 			} else {
+				const changed = option.value !== this.value;
 				this.value = option.value;
+				if (changed) this.emitChange();
 				this.popoverEl?.hide();
 			}
 		};
@@ -104,12 +107,14 @@ var USelect = class USelect extends UFormControlElement {
 			e.preventDefault();
 			e.stopPropagation();
 			this.reset();
+			this.emitChange();
 			this.containerEl?.click();
 		};
 		this.handleChipRemove = (e) => {
 			const value = e.currentTarget.dataset.value;
 			if (!value) return;
 			this.value = this.valueAsArray.filter((v) => v !== value);
+			this.emitChange();
 		};
 	}
 	static {
@@ -263,6 +268,12 @@ var USelect = class USelect extends UFormControlElement {
 		for (const option of this.options) if (this.multiple) option.selected = values.includes(option.value);
 		else option.selected = option.value === this.value;
 		this.internals?.setFormValue(this.valueAsString);
+	}
+	/** 사용자 상호작용으로 값이 바뀐 경로에서만 호출한다 — 프로그램적 value 세팅은
+	*  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다.
+	*  UI 재렌더를 동반한 validate()도 이 경로에서만 수행한다(v1.5.1 검증 아키텍처 —
+	*  updated() 경로는 base의 silent setValidity()만 수행해 Lit 중복 업데이트를 피한다). */
+	emitChange() {
 		if (!this.novalidate) this.validate();
 		this.dispatchEvent(new Event("change", {
 			bubbles: true,
@@ -299,6 +310,15 @@ __decorate([property({
 	attribute: "max-count"
 }), __decorateMetadata("design:type", Number)], USelect.prototype, "maxCount", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], USelect.prototype, "placeholder", void 0);
+__decorate([property({ converter: { fromAttribute: (value) => {
+	if (value == null) return void 0;
+	if (value.trim().startsWith("[")) try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+	return value;
+} } }), __decorateMetadata("design:type", Object)], USelect.prototype, "value", void 0);
 __decorate([query(".container", true), __decorateMetadata("design:type", typeof HTMLElement === "undefined" ? Object : HTMLElement)], USelect.prototype, "containerEl", void 0);
 __decorate([query("u-popover", true), __decorateMetadata("design:type", typeof UPopover === "undefined" ? Object : UPopover)], USelect.prototype, "popoverEl", void 0);
 __decorate([state(), __decorateMetadata("design:type", Array)], USelect.prototype, "options", void 0);

package/dist/components/slider/USlider.d.ts

@@ -32,7 +32,8 @@ export type SliderFormatter = (value: number) => string;
  * @cssprop --slider-mark-color - 마크 색상
  * @cssprop --slider-mark-border-color - 마크 테두리 색상
  *
- * @event change - 드래그 완료 후 값이 확정됐을 때 발생
+ * @event change - 사용자 상호작용으로 값이 확정됐을 때 발생 — 드래그는 완료(pointerup) 시,
+ *   키보드는 조작마다. 프로그램적 value 세팅으로는 발화하지 않는다.
  */
 export declare class USlider extends UFormControlElement<number | number[]> {
     static styles: import('lit').CSSResultGroup[];
@@ -54,6 +55,8 @@ export declare class USlider extends UFormControlElement<number | number[]> {
     max: number;
     /** 값 변경 단위 */
     step: number;
+    /** 슬라이더 값. attribute로는 숫자 또는 range용 JSON 배열(`value='[10,20]'`)을 지원한다. */
+    value?: number | number[];
     private dragging;
     private trackEl;
     private containerEl?;
@@ -72,6 +75,9 @@ export declare class USlider extends UFormControlElement<number | number[]> {
     protected setValidity(): void;
     reset(): void;
     private onChangeValue;
+    /** 사용자 상호작용으로 값이 확정된 경로에서만 호출한다 — 프로그램적 value 세팅은
+     *  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다. */
+    private emitChange;
     private renderThumb;
     private formatDisplay;
     private formatValue;

package/dist/components/slider/USlider.js

@@ -26,6 +26,7 @@ var USlider = class USlider extends UFormControlElement {
 				const pct = Math.max(0, Math.min(rect.width, ev.clientX - rect.left)) / rect.width * 100;
 				return this.percentToVal(pct);
 			};
+			const before = JSON.stringify(this.value);
 			const val = getPointerValue(e);
 			if (this.range) {
 				const closer = Math.abs(val - this.minVal) <= Math.abs(val - this.maxVal) ? "min" : "max";
@@ -47,6 +48,7 @@ var USlider = class USlider extends UFormControlElement {
 				document.removeEventListener("pointermove", handleDocumentMove);
 				document.removeEventListener("pointerup", handleDocumentUp);
 				this.dragging = null;
+				if (JSON.stringify(this.value) !== before) this.emitChange();
 			};
 			document.addEventListener("pointermove", handleDocumentMove);
 			document.addEventListener("pointerup", handleDocumentUp);
@@ -82,9 +84,11 @@ var USlider = class USlider extends UFormControlElement {
 			}
 			e.preventDefault();
 			const newVal = this.snap(currentVal + delta);
+			const before = JSON.stringify(this.value);
 			if (thumb === "min") if (this.range) this.minVal = Math.min(newVal, this.maxVal);
 			else this.value = newVal;
 			else this.maxVal = Math.max(newVal, this.minVal);
+			if (JSON.stringify(this.value) !== before) this.emitChange();
 		};
 	}
 	static {
@@ -197,6 +201,10 @@ var USlider = class USlider extends UFormControlElement {
 		if (Array.isArray(this.value)) this.value = [this.snap(this.value[0]), this.snap(this.value[1])];
 		else if (typeof this.value === "number") this.value = this.snap(this.value);
 		this.internals?.setFormValue(this.valueAsNumber.toString());
+	}
+	/** 사용자 상호작용으로 값이 확정된 경로에서만 호출한다 — 프로그램적 value 세팅은
+	*  네이티브 폼 컨트롤과 동일하게 change를 발화하지 않는다. */
+	emitChange() {
 		this.dispatchEvent(new Event("change", {
 			bubbles: true,
 			composed: true
@@ -229,7 +237,7 @@ var USlider = class USlider extends UFormControlElement {
     `;
 	}
 	formatDisplay() {
-		if (this.range) return `${this.formatValue(this.minVal)} ??${this.formatValue(this.maxVal)}`;
+		if (this.range) return `${this.formatValue(this.minVal)} ~ ${this.formatValue(this.maxVal)}`;
 		else return this.formatValue(this.valueAsNumber);
 	}
 	formatValue(val) {
@@ -269,6 +277,16 @@ __decorate([property({ type: Number }), __decorateMetadata("design:type", Number
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], USlider.prototype, "min", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], USlider.prototype, "max", void 0);
 __decorate([property({ type: Number }), __decorateMetadata("design:type", Number)], USlider.prototype, "step", void 0);
+__decorate([property({ converter: { fromAttribute: (value) => {
+	if (value == null) return void 0;
+	if (value.trim().startsWith("[")) try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+	const n = Number(value);
+	return Number.isNaN(n) ? void 0 : n;
+} } }), __decorateMetadata("design:type", Object)], USlider.prototype, "value", void 0);
 __decorate([state(), __decorateMetadata("design:type", Object)], USlider.prototype, "dragging", void 0);
 __decorate([query(".track"), __decorateMetadata("design:type", typeof HTMLElement === "undefined" ? Object : HTMLElement)], USlider.prototype, "trackEl", void 0);
 __decorate([query(".container"), __decorateMetadata("design:type", typeof HTMLElement === "undefined" ? Object : HTMLElement)], USlider.prototype, "containerEl", void 0);

package/package.json

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