@iyulab/components 0.4.0 → 1.0.0

package/dist/components/UFloatingElement.js

@@ -1,195 +1,238 @@
-import { state, property } from 'lit/decorators.js';
-import { autoUpdate, computePosition, offset, shift, flip, autoPlacement } from '@floating-ui/dom';
-import { getParentElement, querySelectorAllWithin } from '../utilities/elements.js';
-import { UElement } from './UElement.js';
-import { styles } from './UFloatingElement.styles.js';
-
-var __defProp = Object.defineProperty;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = void 0 ;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (decorator(target, key, result) ) || result;
-  if (result) __defProp(target, key, result);
-  return result;
+import { UElement } from "./UElement.js";
+import { __decorateMetadata } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
+import { __decorate } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { getParentElement, querySelectorAllWithin } from "../utilities/elements.js";
+import { styles } from "./UFloatingElement.styles.js";
+import { property, state } from "lit/decorators.js";
+import { arrow, autoPlacement, autoUpdate, computePosition, flip, offset, shift } from "@floating-ui/dom";
+//#region src/components/UFloatingElement.ts
+/**
+* UFloatingElement는 팝오버, 툴팁 등 화면에 떠 있는 엘리먼트를 구현하기 위한 기본 클래스입니다.
+* 이 클래스를 상속하여 커스텀 팝오버 컴포넌트를 만들 수 있습니다.
+* 
+* @event show - 엘리먼트가 표시되기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 표시가 취소됩니다.
+* @event hide - 엘리먼트가 숨겨지기 전에 발생합니다. 이벤트 핸들러에서 false를 반환하면 숨김이 취소됩니다.
+*/
+var UFloatingElement = class extends UElement {
+	constructor(..._args) {
+		super(..._args);
+		this.open = false;
+		this.disabled = false;
+		this.strategy = "absolute";
+		this.offset = 0;
+		this.shift = false;
+		this.arrow = false;
+		this.showDelay = 0;
+		this.hideDelay = 0;
+		this.cleanup = null;
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		if (!this.anchors || this.anchors.length === 0) {
+			const parent = getParentElement(this);
+			this.anchors = parent ? [parent] : [];
+		}
+	}
+	disconnectedCallback() {
+		if (this.cleanup !== null) this.cleanup();
+		this.cleanup = null;
+		clearTimeout(this.showTimer);
+		clearTimeout(this.hideTimer);
+		this.showTimer = void 0;
+		this.hideTimer = void 0;
+		super.disconnectedCallback();
+	}
+	willUpdate(changedProperties) {
+		super.willUpdate(changedProperties);
+		if (changedProperties.has("for")) this.anchors = this.getAnchors(this.for);
+		if (changedProperties.has("arrow")) this.toggleArrowElement(this.arrow);
+	}
+	/** 
+	* 현재 엘리먼트를 표시합니다.
+	* 
+	* @param target - 위치 계산에 사용할 타겟 엘리먼트입니다.
+	* @returns 표시 성공 여부를 나타내는 Promise입니다.
+	*/
+	async show(target) {
+		if (this.disabled) return false;
+		if (this.hideTimer) {
+			clearTimeout(this.hideTimer);
+			this.hideTimer = void 0;
+		}
+		if (this.showTimer) return true;
+		if (this.cleanup !== null) {
+			this.cleanup();
+			this.cleanup = null;
+		}
+		await this.reposition(target);
+		this.cleanup = autoUpdate(target, this, () => {
+			this.reposition(target);
+		});
+		this.targetEl = target;
+		if (this.open) return true;
+		if (this.fire("show")) {
+			if (this.showDelay > 0) this.showTimer = window.setTimeout(() => {
+				this.showTimer = void 0;
+				this.open = true;
+			}, this.showDelay);
+			else this.open = true;
+			return true;
+		}
+		return false;
+	}
+	/** 
+	* 현재 엘리먼트를 숨깁니다.
+	* 
+	* @returns 숨김 성공 여부를 나타내는 Promise입니다.
+	*/
+	async hide() {
+		if (this.disabled) return false;
+		if (this.showTimer) {
+			clearTimeout(this.showTimer);
+			this.showTimer = void 0;
+		}
+		if (this.hideTimer) return true;
+		if (this.cleanup !== null) {
+			this.cleanup();
+			this.cleanup = null;
+		}
+		await this.updateComplete;
+		this.targetEl = void 0;
+		if (!this.open) return true;
+		if (this.fire("hide")) {
+			if (this.hideDelay > 0) this.hideTimer = window.setTimeout(() => {
+				this.hideTimer = void 0;
+				this.open = false;
+			}, this.hideDelay);
+			else this.open = false;
+			return true;
+		}
+		return false;
+	}
+	/** 
+	* `@floating-ui/dom` 를 이용하여 위치를 계산하고 style 을 적용합니다. 
+	* 
+	* @param target - 위치 계산에 사용할 타겟 엘리먼트입니다.
+	*/
+	async reposition(target) {
+		const position = await computePosition(target, this, {
+			strategy: this.strategy,
+			placement: this.placement,
+			middleware: [
+				offset(this.offset),
+				shift({ mainAxis: this.shift }),
+				this.placement ? flip() : autoPlacement(),
+				...this.arrowEl ? [arrow({ element: this.arrowEl })] : []
+			]
+		});
+		const config = {
+			top: {
+				transform: "center bottom",
+				aside: "bottom",
+				clipPath: "polygon(0 0, 100% 0, 50% 70%)"
+			},
+			bottom: {
+				transform: "center top",
+				aside: "top",
+				clipPath: "polygon(50% 30%, 100% 100%, 0 100%)"
+			},
+			left: {
+				transform: "right center",
+				aside: "right",
+				clipPath: "polygon(0 0, 70% 50%, 0 100%)"
+			},
+			right: {
+				transform: "left center",
+				aside: "left",
+				clipPath: "polygon(100% 0, 100% 100%, 30% 50%)"
+			}
+		}[position.placement.split("-")[0]];
+		Object.assign(this.style, {
+			left: `${position.x}px`,
+			top: `${position.y}px`,
+			transformOrigin: config.transform
+		});
+		const arrowData = position.middlewareData.arrow;
+		if (!this.arrowEl || !arrowData) return;
+		Object.assign(this.arrowEl.style, {
+			left: arrowData.x != null ? `${arrowData.x}px` : "",
+			top: arrowData.y != null ? `${arrowData.y}px` : "",
+			right: "",
+			bottom: "",
+			[config.aside]: `-${this.arrowEl.offsetWidth - 1}px`,
+			clipPath: config.clipPath
+		});
+	}
+	/** 
+	* 이벤트에서 사용할 가상 타겟 엘리먼트를 생성합니다. 
+	* 
+	* @param event - 마우스 이벤트 객체입니다.
+	* @returns 가상 타겟 엘리먼트입니다.
+	*/
+	createVirtualTarget(event) {
+		return { getBoundingClientRect: () => ({
+			width: 0,
+			height: 0,
+			x: event.clientX,
+			y: event.clientY,
+			top: event.clientY,
+			left: event.clientX,
+			right: event.clientX,
+			bottom: event.clientY
+		}) };
+	}
+	/** arrow 속성의 변경에 따라 화살표 요소를 추가 또는 제거하는 메서드입니다. */
+	toggleArrowElement(enabled) {
+		if (enabled) {
+			if (this.arrowEl) return;
+			this.arrowEl = document.createElement("div");
+			this.arrowEl.id = "arrow";
+			this.renderRoot.appendChild(this.arrowEl);
+		} else {
+			if (!this.arrowEl) return;
+			this.renderRoot.removeChild(this.arrowEl);
+			this.arrowEl = void 0;
+		}
+	}
+	/** 쿼리 선택자를 사용하여 앵커 엘리먼트를 찾습니다. */
+	getAnchors(selectors) {
+		if (selectors) {
+			const anchors = querySelectorAllWithin(this, selectors);
+			return Array.from(anchors);
+		} else {
+			const parent = getParentElement(this);
+			return parent ? [parent] : [];
+		}
+	}
 };
-class UFloatingElement extends UElement {
-  constructor() {
-    super(...arguments);
-    // 애니메이션 프레임 아이디
-    this.rafId = null;
-    // 자동 위치 업데이트 정리 함수
-    this.cleanup = null;
-    this.visible = false;
-    this.strategy = "absolute";
-    this.distance = 0;
-    this.offset = 0;
-    this.shift = false;
-  }
-  static {
-    /** 기본 스타일을 정의합니다. */
-    this.styles = [super.styles, styles];
-  }
-  static {
-    /** 종속된 컴포넌트를 정의합니다. */
-    this.dependencies = {};
-  }
-  connectedCallback() {
-    super.connectedCallback();
-    if (!this.anchors || this.anchors.length === 0) {
-      const parent = getParentElement(this);
-      this.anchors = parent ? [parent] : [];
-    }
-  }
-  disconnectedCallback() {
-    if (this.rafId !== null) cancelAnimationFrame(this.rafId);
-    if (this.cleanup !== null) this.cleanup();
-    this.rafId = null;
-    this.cleanup = null;
-    super.disconnectedCallback();
-  }
-  willUpdate(changedProperties) {
-    super.willUpdate(changedProperties);
-    if (changedProperties.has("for")) {
-      this.scan(this);
-    }
-  }
-  updated(changedProperties) {
-    super.updated(changedProperties);
-    if (changedProperties.has("visible")) {
-      this.toggleAttribute("aria-hidden", !this.visible);
-      this.toggleAttribute("inert", !this.visible);
-      this.updateVisibleState(this.visible);
-    }
-  }
-  /**
-   * for 속성에 따라 element를 기준으로 앵커 엘리먼트를 탐색하여 anchors로 설정합니다.
-   */
-  scan(element) {
-    if (this.for) {
-      const anchors = querySelectorAllWithin(element, this.for);
-      this.anchors = Array.from(anchors);
-    } else {
-      const parent = getParentElement(this);
-      this.anchors = parent ? [parent] : [];
-    }
-  }
-  /** 
-   * 현재 엘리먼트를 표시합니다.
-   * 
-   * @param target - 위치 계산에 사용할 타겟 엘리먼트입니다.
-   * @param auto - 표시 후 자동 위치 업데이트 활성화 여부입니다. 기본값은 true 입니다.
-   */
-  async show(target, auto = true) {
-    await this.updateComplete;
-    await this.reposition(target);
-    if (auto === true) {
-      this.cleanup = autoUpdate(target, this, () => {
-        this.reposition(target);
-      });
-    }
-    this.scheduleVisible(true);
-    this.target = target;
-  }
-  /** 
-   * 현재 엘리먼트를 숨깁니다.
-   */
-  async hide() {
-    await this.updateComplete;
-    if (this.cleanup !== null) this.cleanup();
-    this.cleanup = null;
-    this.scheduleVisible(false);
-    this.target = void 0;
-  }
-  /** 
-   * `floating-ui` 를 이용하여 위치를 계산하고 style 을 적용합니다. 
-   * 
-   * @param target - 위치 계산에 사용할 타겟 엘리먼트입니다.
-   */
-  async reposition(target) {
-    const position = await computePosition(target, this, {
-      strategy: this.strategy,
-      placement: this.placement,
-      middleware: [
-        offset({ mainAxis: this.distance, crossAxis: this.offset }),
-        shift({ mainAxis: this.shift }),
-        this.placement ? flip() : autoPlacement()
-      ]
-    });
-    Object.assign(this.style, {
-      left: `${position.x}px`,
-      top: `${position.y}px`,
-      // placement 에 따라 transform-origin 값을 결정합니다.(애니메이션용)
-      transformOrigin: (() => {
-        switch (position.placement) {
-          case "top":
-          case "top-start":
-          case "top-end":
-            return "center bottom";
-          case "bottom":
-          case "bottom-start":
-          case "bottom-end":
-            return "center top";
-          case "left":
-          case "left-start":
-          case "left-end":
-            return "right center";
-          case "right":
-          case "right-start":
-          case "right-end":
-            return "left center";
-          default:
-            return "center";
-        }
-      })()
-    });
-  }
-  /** 표시 상태 변경 이벤트를 발생시킵니다. */
-  updateVisibleState(visible) {
-    if (visible) {
-      this.emit("u-show");
-    } else {
-      this.emit("u-hide");
-    }
-  }
-  /** 애니메이션 프레임을 사용하여 표시 상태를 스케줄링합니다. */
-  scheduleVisible(visible) {
-    if (this.rafId !== null) {
-      cancelAnimationFrame(this.rafId);
-      this.rafId = null;
-    }
-    this.rafId = requestAnimationFrame(() => {
-      this.visible = visible;
-      this.rafId = null;
-    });
-  }
-}
-__decorateClass([
-  state()
-], UFloatingElement.prototype, "target");
-__decorateClass([
-  state()
-], UFloatingElement.prototype, "anchors");
-__decorateClass([
-  property({ type: String, reflect: true })
-], UFloatingElement.prototype, "for");
-__decorateClass([
-  property({ type: Boolean, reflect: true })
-], UFloatingElement.prototype, "visible");
-__decorateClass([
-  property({ type: String, reflect: true })
-], UFloatingElement.prototype, "strategy");
-__decorateClass([
-  property({ type: String })
-], UFloatingElement.prototype, "placement");
-__decorateClass([
-  property({ type: Number })
-], UFloatingElement.prototype, "distance");
-__decorateClass([
-  property({ type: Number })
-], UFloatingElement.prototype, "offset");
-__decorateClass([
-  property({ type: Boolean })
-], UFloatingElement.prototype, "shift");
-
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFloatingElement.prototype, "open", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFloatingElement.prototype, "disabled", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+}), __decorateMetadata("design:type", String)], UFloatingElement.prototype, "for", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UFloatingElement.prototype, "strategy", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UFloatingElement.prototype, "placement", void 0);
+__decorate([property({ type: Number }), __decorateMetadata("design:type", Object)], UFloatingElement.prototype, "offset", void 0);
+__decorate([property({ type: Boolean }), __decorateMetadata("design:type", Boolean)], UFloatingElement.prototype, "shift", void 0);
+__decorate([property({ type: Boolean }), __decorateMetadata("design:type", Boolean)], UFloatingElement.prototype, "arrow", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "show-delay"
+}), __decorateMetadata("design:type", Number)], UFloatingElement.prototype, "showDelay", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "hide-delay"
+}), __decorateMetadata("design:type", Number)], UFloatingElement.prototype, "hideDelay", void 0);
+__decorate([state(), __decorateMetadata("design:type", Array)], UFloatingElement.prototype, "anchors", void 0);
+//#endregion
 export { UFloatingElement };

package/dist/components/UFloatingElement.styles.d.ts

@@ -1 +1,9 @@
+/**
+ * **주의**:
+ * 조상 요소에 transform + overflow의 조합일 경우,
+ * floating element가 뷰포트가 아닌 부모 요소를 기준으로 위치하게 됩니다.
+ * 이 경우, floating element가 부모 요소의 경계를 벗어나지 못하게 됩니다.
+ *
+ * **해결 방안**: 상위 레이어로 위치 변경
+ */
 export declare const styles: import('lit').CSSResult;

package/dist/components/UFloatingElement.styles.js

@@ -1,16 +1,31 @@
-import { css } from 'lit';
-
-const styles = css`
+import { css } from "lit";
+//#region src/components/UFloatingElement.styles.ts
+/**
+* **주의**: 
+* 조상 요소에 transform + overflow의 조합일 경우, 
+* floating element가 뷰포트가 아닌 부모 요소를 기준으로 위치하게 됩니다.
+* 이 경우, floating element가 부모 요소의 경계를 벗어나지 못하게 됩니다.
+* 
+* **해결 방안**: 상위 레이어로 위치 변경
+*/
+var styles = css`
   :host {
     position: absolute;
     z-index: 1000;
     top: 0;
     left: 0;
     width: max-content;
+
     opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition: opacity 0.2s ease, visibility 0s 0.2s;
   }
-  :host([visible]) {
+  :host([open]) {
     opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+    transition-delay: 0s;
   }
   :host([strategy="absolute"]) {
     position: absolute;
@@ -18,6 +33,14 @@ const styles = css`
   :host([strategy="fixed"]) {
     position: fixed;
   }
-`;
 
+  /* 화살표: clip-path로 삼각형 */
+  #arrow {
+    position: absolute;
+    width: 0.5em;
+    height: 0.5em;
+    background-color: inherit;
+  }
+`;
+//#endregion
 export { styles };

package/dist/components/UFormControlElement.d.ts

@@ -0,0 +1,57 @@
+import { CSSResultGroup } from 'lit';
+import { UElement } from './UElement.js';
+/**
+ * 폼 컨트롤 컴포넌트의 공통 기반 클래스입니다.
+ * 사용자 입력을 받는 모든 컴포넌트가 이 클래스를 확장합니다.
+ */
+export declare abstract class UFormControlElement<T> extends UElement {
+    static styles: CSSResultGroup;
+    static formAssociated: boolean;
+    /** 비활성 상태 */
+    disabled: boolean;
+    /** 읽기 전용 상태 */
+    readonly: boolean;
+    /** 필수 입력 여부 */
+    required: boolean;
+    /** 유효성 검증 실패 상태 */
+    invalid: boolean;
+    /** 값 변경시 자동 유효성 검증 여부 */
+    novalidate: boolean;
+    /** 필드 라벨 */
+    label?: string;
+    /** 보조 설명 텍스트 */
+    description?: string;
+    /** 커스텀 유효성 검증 메시지 */
+    validationMessage?: string;
+    /** 폼 제출 시 사용되는 이름 */
+    name?: string;
+    /** 폼 제출 시 사용되는 값 */
+    value?: T;
+    /**
+     * ElementInternals는 폼과의 연동, 유효성 검사 상태 관리 등을 지원하는 네이티브 API입니다.
+     */
+    protected internals?: ElementInternals;
+    /**
+     * 폼과의 연동을 위해 `form` 속성을 제공합니다. ElementInternals를 지원하는 브라우저에서 폼 요소에 접근할 수 있습니다.
+     * 지원하지 않는 브라우저에서는 null을 반환합니다.
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * 각 컴포넌트가 자신의 검증 로직으로 validity 상태를 갱신하면, 이 객체를 통해 유효성 상태를 확인할 수 있습니다.
+     * ElementInternals를 지원하지 않는 브라우저에서는 undefined를 반환합니다.
+     */
+    get validity(): ValidityState | undefined;
+    connectedCallback(): void;
+    /**
+     * 컴포넌트 자체 유효성을 검증하고 `invalid` 상태를 갱신합니다.
+     * 각 컴포넌트가 자신의 검증 로직으로 구현합니다.
+     *
+     * @returns 유효하면 `true`, 아니면 `false`
+     */
+    abstract validate(): boolean;
+    /**
+     * 폼이 리셋될 때 호출되는 메서드입니다.
+     * 각 컴포넌트가 자신의 초기 상태로 리셋하는 로직을 구현합니다.
+     */
+    abstract reset(): void;
+}

package/dist/components/UFormControlElement.js

@@ -0,0 +1,68 @@
+import { UElement } from "./UElement.js";
+import { styles } from "./UFormControlElement.styles.js";
+import { __decorateMetadata } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
+import { __decorate } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { property } from "lit/decorators.js";
+//#region src/components/UFormControlElement.ts
+/**
+* 폼 컨트롤 컴포넌트의 공통 기반 클래스입니다.
+* 사용자 입력을 받는 모든 컴포넌트가 이 클래스를 확장합니다.
+*/
+var UFormControlElement = class extends UElement {
+	constructor(..._args) {
+		super(..._args);
+		this.disabled = false;
+		this.readonly = false;
+		this.required = false;
+		this.invalid = false;
+		this.novalidate = false;
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	static {
+		this.formAssociated = true;
+	}
+	/** 
+	* 폼과의 연동을 위해 `form` 속성을 제공합니다. ElementInternals를 지원하는 브라우저에서 폼 요소에 접근할 수 있습니다.
+	* 지원하지 않는 브라우저에서는 null을 반환합니다. 
+	*/
+	get form() {
+		return this.internals?.form ?? null;
+	}
+	/** 
+	* 각 컴포넌트가 자신의 검증 로직으로 validity 상태를 갱신하면, 이 객체를 통해 유효성 상태를 확인할 수 있습니다.
+	* ElementInternals를 지원하지 않는 브라우저에서는 undefined를 반환합니다.
+	*/
+	get validity() {
+		return this.internals?.validity;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		if ("attachInternals" in this) this.internals = this.attachInternals();
+	}
+};
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFormControlElement.prototype, "disabled", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFormControlElement.prototype, "readonly", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFormControlElement.prototype, "required", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UFormControlElement.prototype, "invalid", void 0);
+__decorate([property({ type: Boolean }), __decorateMetadata("design:type", Boolean)], UFormControlElement.prototype, "novalidate", void 0);
+__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, "validationMessage", 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);
+//#endregion
+export { UFormControlElement };

package/dist/components/UFormControlElement.styles.js

@@ -0,0 +1,14 @@
+import { css } from "lit";
+//#region src/components/UFormControlElement.styles.ts
+var styles = css`
+  :host([disabled]) {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+
+  :host([readonly]) {
+    pointer-events: none;
+  }
+`;
+//#endregion
+export { styles };