@iyulab/components 1.22.0 → 1.24.0

package/dist/components/tree-item/UTreeItem.js

@@ -22,7 +22,6 @@ var UTreeItem = class UTreeItem extends UElement {
 		this.trigger = "item";
 		this.value = "";
 		this.draggable = false;
-		this.droppable = false;
 		this.leaf = true;
 		this.depth = 0;
 		this.selected = false;
@@ -185,10 +184,6 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "draggable", void 0);
-__decorate([property({
-	type: Boolean,
-	reflect: true
-}), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "droppable", void 0);
 __decorate([state(), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "leaf", void 0);
 __decorate([state(), __decorateMetadata("design:type", Number)], UTreeItem.prototype, "depth", void 0);
 __decorate([state(), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "selected", void 0);

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './components/copy-button/UCopyButton.js';
 export * from './components/dialog/UDialog.js';
 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/form/UForm.js';
 export * from './components/icon/UIcon.js';
@@ -40,6 +41,7 @@ export * from './components/switch/USwitch.js';
 export * from './components/tab/UTab.js';
 export * from './components/tab-panel/UTabPanel.js';
 export * from './components/tag/UTag.js';
+export * from './components/text/UText.js';
 export * from './components/textarea/UTextarea.js';
 export * from './components/tooltip/UTooltip.js';
 export * from './components/tree/UTree.js';

package/dist/index.js

@@ -27,6 +27,7 @@ import { UCopyButton } from "./components/copy-button/UCopyButton.js";
 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 { UField } from "./components/field/UField.js";
 import { UForm } from "./components/form/UForm.js";
 import { UOption } from "./components/option/UOption.js";
@@ -46,6 +47,7 @@ import { USplitPanel } from "./components/split-panel/USplitPanel.js";
 import { USwitch } from "./components/switch/USwitch.js";
 import { UTab } from "./components/tab/UTab.js";
 import { UTabPanel } from "./components/tab-panel/UTabPanel.js";
+import { UText } from "./components/text/UText.js";
 import { UTextarea } from "./components/textarea/UTextarea.js";
 import { UTreeItem } from "./components/tree-item/UTreeItem.js";
 import { UTree } from "./components/tree/UTree.js";
@@ -53,4 +55,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, UDialog, UDivider, UDrawer, UElement, 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, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, getDefaultBaseUrl, getParentElement, 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, 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, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };

package/dist/react/UExpander.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { UExpander as UExpanderElement } from '../components/expander/UExpander';
+import { type ExpandEventDetail } from '../events/ExpandEvent';
+import { type CollapseEventDetail } from '../events/CollapseEvent';
+
+export declare const UExpander: React.ForwardRefExoticComponent<
+  Omit<Partial<UExpanderElement>, keyof React.HTMLAttributes<UExpanderElement>>
+    & Omit<React.HTMLAttributes<UExpanderElement>, 'onExpand' | 'onCollapse'>
+    & React.RefAttributes<UExpanderElement>
+    & {
+  onExpand?: (event: CustomEvent<ExpandEventDetail>) => void;
+  onCollapse?: (event: CustomEvent<CollapseEventDetail>) => void;
+  }
+>;
+
+export type UExpanderProps = React.ComponentProps<typeof UExpander>;

package/dist/react/UExpander.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UExpander as UExpanderElement } from '../components/expander/UExpander.js';
+
+export const UExpander = createComponent({
+  react: React,
+  tagName: 'u-expander',
+  elementClass: UExpanderElement,
+  events: {
+    onExpand: 'expand',
+    onCollapse: 'collapse',
+  },
+});

package/dist/react/UText.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { UText as UTextElement } from '../components/text/UText';
+
+export declare const UText: React.ForwardRefExoticComponent<
+  Omit<Partial<UTextElement>, keyof React.HTMLAttributes<UTextElement>>
+    & Omit<React.HTMLAttributes<UTextElement>, never>
+    & React.RefAttributes<UTextElement>
+    & {
+  }
+>;
+
+export type UTextProps = React.ComponentProps<typeof UText>;

package/dist/react/UText.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UText as UTextElement } from '../components/text/UText.js';
+
+export const UText = createComponent({
+  react: React,
+  tagName: 'u-text',
+  elementClass: UTextElement,
+  events: {},
+});

package/dist/react/index.d.ts

@@ -2,6 +2,7 @@ export { UTreeItem, UTreeItemProps } from './UTreeItem';
 export { UTree, UTreeProps } from './UTree';
 export { UTooltip, UTooltipProps } from './UTooltip';
 export { UTextarea, UTextareaProps } from './UTextarea';
+export { UText, UTextProps } from './UText';
 export { UTag, UTagProps } from './UTag';
 export { UTabPanel, UTabPanelProps } from './UTabPanel';
 export { UTab, UTabProps } from './UTab';
@@ -25,6 +26,7 @@ export { UIconButton, UIconButtonProps } from './UIconButton';
 export { UIcon, UIconProps } from './UIcon';
 export { UForm, UFormProps } from './UForm';
 export { UField, UFieldProps } from './UField';
+export { UExpander, UExpanderProps } from './UExpander';
 export { UDrawer, UDrawerProps } from './UDrawer';
 export { UDivider, UDividerProps } from './UDivider';
 export { UDialog, UDialogProps } from './UDialog';

package/dist/react/index.js

@@ -2,6 +2,7 @@ export { UTreeItem } from './UTreeItem.js';
 export { UTree } from './UTree.js';
 export { UTooltip } from './UTooltip.js';
 export { UTextarea } from './UTextarea.js';
+export { UText } from './UText.js';
 export { UTag } from './UTag.js';
 export { UTabPanel } from './UTabPanel.js';
 export { UTab } from './UTab.js';
@@ -25,6 +26,7 @@ export { UIconButton } from './UIconButton.js';
 export { UIcon } from './UIcon.js';
 export { UForm } from './UForm.js';
 export { UField } from './UField.js';
+export { UExpander } from './UExpander.js';
 export { UDrawer } from './UDrawer.js';
 export { UDivider } from './UDivider.js';
 export { UDialog } from './UDialog.js';

package/dist/utilities/Dialog.js

@@ -115,7 +115,7 @@ var Dialog = class {
 		try {
 			await dialog.updateComplete;
 		} catch (error) {
-			console.error("[Dialog] 다이얼로그를 표시하지 못했습니다.", error);
+			console.error("[Dialog] Failed to show the dialog.", error);
 			dialog.remove();
 			return null;
 		}

package/dist/utilities/Locale.d.ts

@@ -14,6 +14,31 @@ export type LocaleTag = SupportedLocale | (string & {});
 /** 라이브러리가 제공하는 chrome 문자열 키. 지금은 검증 메시지뿐이지만 이후 다른 UI 문구도 추가될 수 있다. */
 export type LocaleMessageKey = 'valueMissing' | 'badInput' | 'typeMismatch' | 'patternMismatch' | 'rangeUnderflow' | 'rangeOverflow' | 'stepMismatch' | 'tooShort' | 'tooLong';
 type LocaleTable = Record<LocaleMessageKey, string>;
+/**
+ * 한 패키지(또는 앱 영역)의 문자열 묶음.
+ *
+ * 키 유니온을 **소비자가** 정하므로 라이브러리의 키셋은 커지지 않는다:
+ * ```ts
+ * const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+ * t.register('en', { empty: 'No data', loading: 'Loading…' });
+ * t.text('empty');
+ * ```
+ */
+export interface LocaleNamespace<K extends string = string> {
+    /** 네임스페이스 이름. */
+    readonly name: string;
+    /**
+     * 로케일 하나의 테이블(전체 또는 일부)을 등록한다.
+     * 같은 로케일에 반복 호출하면 **병합**된다 — 일부 키만 넘겨도 나머지가 사라지지 않는다.
+     */
+    register(locale: LocaleTag, table: Partial<Record<K, string>>): void;
+    /**
+     * 활성 로케일 기준으로 문자열을 찾는다.
+     * 사슬(정확 일치 → base → en)에 없으면 **키 자체를 돌려준다** — 조용히 빈 문자열이
+     * 되는 것보다 화면에 드러나는 편이 낫다.
+     */
+    text(key: K, params?: Record<string, string | number>): string;
+}
 /**
  * 검증 메시지 로케일을 관리하는 정적 유틸리티입니다.
  */
@@ -34,5 +59,14 @@ export declare class Locale {
      * `params`가 있으면 템플릿의 `{name}` 자리를 치환합니다.
      */
     static getValue(key: LocaleMessageKey, params?: Record<string, string | number>): string;
+    /**
+     * 네임스페이스 핸들을 얻습니다 — 같은 이름이면 **같은 저장소**를 가리킵니다.
+     *
+     * 상위 패키지가 자기 화면 문자열을 담는 자리입니다. 검증 메시지(`getValue`)의 키셋과
+     * 완전히 분리돼 있어, 이 API 를 써도 라이브러리의 `LocaleMessageKey` 는 커지지 않습니다.
+     *
+     * @param name 네임스페이스 이름. 패키지·컴포넌트 단위를 권장합니다(예: `'u-data-view'`).
+     */
+    static namespace<K extends string = string>(name: string): LocaleNamespace<K>;
 }
 export {};

package/dist/utilities/Locale.js

@@ -39,21 +39,29 @@ function detectLocale() {
 	return "en";
 }
 var active = detectLocale();
-/** 정확 일치 → base 언어(ko-KR → ko) → en 순으로 값을 찾는다. */
-function lookup(locale, key) {
+/** 정확 일치 → base 언어(ko-KR → ko) → en 순의 조회 사슬. */
+function chainOf(locale) {
 	const norm = locale.toLowerCase();
 	const base = norm.split("-")[0];
-	const chain = base === norm ? [norm, "en"] : [
+	return base === norm ? [norm, "en"] : [
 		norm,
 		base,
 		"en"
 	];
-	for (const tag of chain) {
+}
+/** 템플릿의 `{name}` 자리를 치환한다. 값이 없는 자리는 그대로 남긴다(디버깅 단서). */
+function interpolate(template, params) {
+	return params ? template.replace(/\{(\w+)\}/g, (_, name) => params[name] != null ? String(params[name]) : `{${name}}`) : template;
+}
+function lookup(locale, key) {
+	for (const tag of chainOf(locale)) {
 		const value = overrides.get(tag)?.[key] ?? builtins.get(tag)?.[key];
 		if (value) return value;
 	}
 	return builtins.get("en")[key];
 }
+/** ns → 정규화 로케일 태그 → 테이블. */
+var namespaces = /* @__PURE__ */ new Map();
 /**
 * 검증 메시지 로케일을 관리하는 정적 유틸리티입니다.
 */
@@ -85,8 +93,37 @@ var Locale = class {
 	* `params`가 있으면 템플릿의 `{name}` 자리를 치환합니다.
 	*/
 	static getValue(key, params) {
-		const template = lookup(active, key);
-		return params ? template.replace(/\{(\w+)\}/g, (_, name) => params[name] != null ? String(params[name]) : `{${name}}`) : template;
+		return interpolate(lookup(active, key), params);
+	}
+	/**
+	* 네임스페이스 핸들을 얻습니다 — 같은 이름이면 **같은 저장소**를 가리킵니다.
+	*
+	* 상위 패키지가 자기 화면 문자열을 담는 자리입니다. 검증 메시지(`getValue`)의 키셋과
+	* 완전히 분리돼 있어, 이 API 를 써도 라이브러리의 `LocaleMessageKey` 는 커지지 않습니다.
+	*
+	* @param name 네임스페이스 이름. 패키지·컴포넌트 단위를 권장합니다(예: `'u-data-view'`).
+	*/
+	static namespace(name) {
+		return {
+			name,
+			register(locale, table) {
+				const byLocale = namespaces.get(name) ?? /* @__PURE__ */ new Map();
+				const norm = locale.toLowerCase();
+				byLocale.set(norm, {
+					...byLocale.get(norm),
+					...table
+				});
+				namespaces.set(name, byLocale);
+			},
+			text(key, params) {
+				const byLocale = namespaces.get(name);
+				for (const tag of chainOf(active)) {
+					const value = byLocale?.get(tag)?.[key];
+					if (value) return interpolate(value, params);
+				}
+				return key;
+			}
+		};
 	}
 };
 //#endregion

package/dist/utilities/Theme.d.ts

@@ -65,6 +65,43 @@ export declare class Theme {
     static set(theme: ThemeType): void;
     /** 시스템 테마 변경을 처리하는 메서드 */
     private static handleSystemThemeChanged;
+    /** 마지막으로 지정된 브랜드 시드. 테마가 바뀌면 이 값으로 램프를 다시 계산한다. */
+    private static accentSeed;
+    /**
+     * 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.
+     *
+     * ```ts
+     * Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+     * Theme.accent(null);        // 해제 — 시트 기본값으로 되돌아간다
+     * ```
+     *
+     * 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+     * 아무것도 확인하지 않았다. 여기서는 «면 위 글자 4.5 · 바탕 위 글자 4.5 · 단 구분 1.20 ·
+     * 그래픽 3.0» 을 만족하는 값을 **계산해서** 넣는다(`utilities/accent.ts`).
+     *
+     * ⚠**바탕은 계산 시점의 `--u-bg-color` 를 읽는다** — 소비자가 바탕을 덮었으면 그 값을
+     * 기준으로 계산되고, 테마가 바뀌면 **다시 계산한다**(라이트/다크가 다른 램프를 갖는다).
+     * ⇒ `Theme.set()` · 시스템 테마 변경 뒤에 자동으로 재적용된다.
+     *
+     * ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
+     * 로드 순서에 기대지 않는다.
+     *
+     * 🔴**`--u-primary-bg-color` 는 세팅하지 않는다 — 이 자가 덮는 것은 7종 중 6종이다.**
+     * 그 토큰은 «글자를 얹는 옅은 면»(`u-tag` 의 `--tag-hue-surface`)이라 램프의 어느 단과도
+     * 성질이 다르고, 시트는 그 자리를 **5계열 × 2테마 = 10개 값으로 손수 짝지어** 두었다
+     * (라이트/다크가 같은 대비비를 쓰지 않는다 — 실측 1.14 대 1.03). 도출식으로 바꾸는 것은
+     * 팔레트 값 결정이라 사람 판단이 필요하다.
+     *
+     * ⇒ **시드만 넣으면 태그·선택된 행 같은 옅은 면이 파랑으로 남는다.** 함께 세팅할 것:
+     *
+     * ```ts
+     * Theme.accent('#7c3aed');
+     * document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+     * ```
+     */
+    static accent(seed: string | null): void;
+    /** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */
+    private static applyAccent;
     /** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
     private static log;
 }

package/dist/utilities/Theme.js

@@ -1,7 +1,17 @@
 import { BrowserStorage } from "./BrowserStorage.js";
 import dark_css_default from "../_virtual/_glob-assets_raw/dark.css.e8ac080d.js";
 import light_css_default from "../_virtual/_glob-assets_raw/light.css.637cb2f8.js";
+import { accentCustomProperties, deriveAccentRamp } from "./accent.js";
 //#region src/utilities/Theme.ts
+/** 프로퍼티 «이름»만 필요할 때 쓰는 더미 — 값은 쓰지 않는다. */
+var EMPTY_RAMP = {
+	weakest: "#000",
+	weaker: "#000",
+	weak: "#000",
+	color: "#000",
+	strong: "#000",
+	txt: "#000"
+};
 /**
 * 스타일 시트 번들 로드, 내부 자산에서 CSS를 인라인으로 가져옵니다.
 * 빌드 시점에 정적 파일을 포함시키기 위해 vite의 `import.meta.glob`을 사용합니다.
@@ -139,6 +149,7 @@ var Theme = class {
 		} catch (e) {
 			this.log("Error applying theme:", e);
 		}
+		this.applyAccent();
 		if (this.storage !== null) {
 			this.storage.set(this.STORAGE_THEME_KEY, theme);
 			this.log("saved theme to storage", theme);
@@ -150,9 +161,63 @@ var Theme = class {
 				const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
 				document.documentElement.setAttribute("theme", isDark ? "dark" : "light");
 				this.log("system theme changed, applied", isDark ? "dark" : "light");
+				this.applyAccent();
 			}
 		};
 	}
+	static {
+		this.accentSeed = null;
+	}
+	/**
+	* 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.
+	*
+	* ```ts
+	* Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+	* Theme.accent(null);        // 해제 — 시트 기본값으로 되돌아간다
+	* ```
+	*
+	* 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+	* 아무것도 확인하지 않았다. 여기서는 «면 위 글자 4.5 · 바탕 위 글자 4.5 · 단 구분 1.20 ·
+	* 그래픽 3.0» 을 만족하는 값을 **계산해서** 넣는다(`utilities/accent.ts`).
+	*
+	* ⚠**바탕은 계산 시점의 `--u-bg-color` 를 읽는다** — 소비자가 바탕을 덮었으면 그 값을
+	* 기준으로 계산되고, 테마가 바뀌면 **다시 계산한다**(라이트/다크가 다른 램프를 갖는다).
+	* ⇒ `Theme.set()` · 시스템 테마 변경 뒤에 자동으로 재적용된다.
+	*
+	* ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
+	* 로드 순서에 기대지 않는다.
+	*
+	* 🔴**`--u-primary-bg-color` 는 세팅하지 않는다 — 이 자가 덮는 것은 7종 중 6종이다.**
+	* 그 토큰은 «글자를 얹는 옅은 면»(`u-tag` 의 `--tag-hue-surface`)이라 램프의 어느 단과도
+	* 성질이 다르고, 시트는 그 자리를 **5계열 × 2테마 = 10개 값으로 손수 짝지어** 두었다
+	* (라이트/다크가 같은 대비비를 쓰지 않는다 — 실측 1.14 대 1.03). 도출식으로 바꾸는 것은
+	* 팔레트 값 결정이라 사람 판단이 필요하다.
+	*
+	* ⇒ **시드만 넣으면 태그·선택된 행 같은 옅은 면이 파랑으로 남는다.** 함께 세팅할 것:
+	*
+	* ```ts
+	* Theme.accent('#7c3aed');
+	* document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+	* ```
+	*/
+	static accent(seed) {
+		this.accentSeed = seed;
+		this.applyAccent();
+	}
+	/** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */
+	static applyAccent() {
+		if (typeof document === "undefined") return;
+		const root = document.documentElement;
+		const names = Object.keys(accentCustomProperties(EMPTY_RAMP));
+		if (!this.accentSeed) {
+			for (const n of names) root.style.removeProperty(n);
+			return;
+		}
+		const bg = getComputedStyle(root).getPropertyValue("--u-bg-color").trim() || "#ffffff";
+		const ramp = deriveAccentRamp(this.accentSeed, bg);
+		for (const [name, value] of Object.entries(accentCustomProperties(ramp))) root.style.setProperty(name, value);
+		this.log("accent applied", this.accentSeed, "→", ramp);
+	}
 	/** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
 	static log(...args) {
 		if (this._isDebugMode) console.log("[theme]", ...args);

package/dist/utilities/accent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * **브랜드 악센트 시드 → 역할 램프 파생.**
+ *
+ * 소비자가 시드 색 하나를 주면 `--u-primary-*` 5단과 그 면 위의 글자색을 계산한다.
+ * 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값들이 대비 계약을 만족하는지는
+ * 아무것도 확인하지 않았다.
+ *
+ * ## 🔴 왜 CSS 만으로 하지 않는가 — 실측이 정한 것이다
+ *
+ * `color-mix()` 로 고정 비율만 섞으면 **밝은 시드에서 계약이 깨진다** — 노랑 시드의
+ * `-strong` 이 바탕 대비 **2.21**(기준 4.5)이었다. 목표 대비까지 섞으려면 **대비를 계산**
+ * 해야 하고 CSS 에는 그 수단이 없다. ⇒ 계산은 JS 가 하고, 결과만 커스텀 프로퍼티로 넣는다.
+ *
+ * ## ⚠ 두 목표를 «동시에» 건다
+ *
+ * 대비만 목표로 삼으면 시드가 이미 4.5 를 넘을 때 탐색이 **시드 자신에서 멈춰**
+ * `-strong` 과 `-color` 가 같은 값이 된다(실측: 5역할 중 4). 그러면 계약은 만족하는데
+ * **위계가 사라진다.** 그래서 «바탕과 4.5» 와 «`-color` 와 1.20» 을 함께 만족시킨다.
+ *
+ * ## 방향은 «바탕 기준»이다 — 라이트/다크가 같은 코드로 돈다
+ *
+ * `-strong` 은 바탕에서 **멀어지는** 쪽(라이트면 검정, 다크면 흰색), `-weak` 이하는 바탕에
+ * **가까워지는** 쪽이다. 다크 시트가 팔레트를 반전시켜 놓은 것과 같은 방향이다.
+ */
+/** 역할 램프 한 벌. 시트의 `--u-{role}-color-*` 와 이름이 1:1 이다. */
+export interface AccentRamp {
+    weakest: string;
+    weaker: string;
+    weak: string;
+    color: string;
+    strong: string;
+    /** 면(`color`) 위에 놓이는 글자색 — `--u-{role}-txt-color`. */
+    txt: string;
+}
+/** 대비 계약의 문턱값 — `tests/build/token-contrast.test.ts` 와 같은 값이다. */
+export declare const AA_TEXT = 4.5;
+export declare const AA_GRAPHIC = 3;
+/** `-strong` 이 `-color` 와 갈려 보이기 위한 최소 대비(2026-08-04 채택). */
+export declare const MIN_STEP_SEPARATION = 1.2;
+/** `#rgb`·`#rrggbb`·`rgb(r g b)` 를 [r,g,b] 로. 해석할 수 없으면 `null`. */
+export declare function parseColor(value: string): [number, number, number] | null;
+export declare function toHex([r, g, b]: [number, number, number]): string;
+export declare function luminance(color: string): number;
+/** WCAG 2.1 명암비. */
+export declare function contrast(a: string, b: string): number;
+/** `color-mix(in srgb, a p%, b)` 와 같은 계산. */
+export declare function mix(a: string, b: string, p: number): string;
+/** 면 위의 글자를 고른다 — 검정/흰색 중 대비가 큰 쪽. */
+export declare function pickOnColor(surface: string): string;
+export declare function deriveAccentRamp(seed: string, bg: string): AccentRamp;
+/** 램프를 커스텀 프로퍼티 이름 → 값 맵으로. */
+export declare function accentCustomProperties(ramp: AccentRamp, role?: string): Record<string, string>;

package/dist/utilities/accent.js

@@ -0,0 +1,127 @@
+//#region src/utilities/accent.ts
+/** 대비 계약의 문턱값 — `tests/build/token-contrast.test.ts` 와 같은 값이다. */
+var AA_TEXT = 4.5;
+/** `-strong` 이 `-color` 와 갈려 보이기 위한 최소 대비(2026-08-04 채택). */
+var MIN_STEP_SEPARATION = 1.2;
+var clamp = (v) => Math.min(255, Math.max(0, v));
+var channelLum = (c) => c <= .03928 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
+/** `#rgb`·`#rrggbb`·`rgb(r g b)` 를 [r,g,b] 로. 해석할 수 없으면 `null`. */
+function parseColor(value) {
+	const v = value.trim();
+	const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(v);
+	if (hex) {
+		const h = hex[1].length === 3 ? hex[1].replace(/./g, (c) => c + c) : hex[1];
+		const n = parseInt(h, 16);
+		return [
+			n >> 16 & 255,
+			n >> 8 & 255,
+			n & 255
+		];
+	}
+	const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(v);
+	if (rgb) return [
+		Number(rgb[1]),
+		Number(rgb[2]),
+		Number(rgb[3])
+	];
+	return null;
+}
+function toHex([r, g, b]) {
+	return "#" + [
+		r,
+		g,
+		b
+	].map((v) => Math.round(clamp(v)).toString(16).padStart(2, "0")).join("");
+}
+function luminance(color) {
+	const rgb = parseColor(color);
+	if (!rgb) return 0;
+	const [r, g, b] = rgb.map((v) => channelLum(v / 255));
+	return .2126 * r + .7152 * g + .0722 * b;
+}
+/** WCAG 2.1 명암비. */
+function contrast(a, b) {
+	const [x, y] = [luminance(a), luminance(b)];
+	return (Math.max(x, y) + .05) / (Math.min(x, y) + .05);
+}
+/** `color-mix(in srgb, a p%, b)` 와 같은 계산. */
+function mix(a, b, p) {
+	const [x, y] = [parseColor(a), parseColor(b)];
+	if (!x || !y) return a;
+	return toHex([
+		0,
+		1,
+		2
+	].map((i) => x[i] * p + y[i] * (1 - p)));
+}
+/** 면 위의 글자를 고른다 — 검정/흰색 중 대비가 큰 쪽. */
+function pickOnColor(surface) {
+	return contrast(surface, "#000000") >= contrast(surface, "#ffffff") ? "#000000" : "#ffffff";
+}
+/**
+* 시드에서 `--u-primary-*` 램프를 만든다.
+*
+* @param seed 브랜드 색
+* @param bg   그 램프가 놓일 바탕(`--u-bg-color`) — 라이트/다크가 이 값 하나로 갈린다
+*/
+var STEP = .02;
+/**
+* `from` 에서 `target` 쪽으로 조금씩 옮기며 **조건을 만족하는 첫 색**을 돌려준다.
+* 못 찾으면 `null` — 호출부가 반대 방향을 시도한다.
+*/
+function towards(from, target, ok) {
+	for (let p = 1; p >= 0; p -= STEP) {
+		const c = mix(from, target, p);
+		if (ok(c)) return c;
+	}
+	return null;
+}
+function deriveAccentRamp(seed, bg) {
+	const light = luminance(bg) > .5;
+	const away = light ? "#000000" : "#ffffff";
+	const near = light ? "#ffffff" : "#000000";
+	/**
+	* 🔴**방향은 항상 «바탕에서 멀어지는 쪽»이 아니다 — 실측이 이 폴백을 만들게 했다.**
+	*
+	*   `#F5F5F5` 시드 + 다크 바탕 → `-strong` 을 흰색 쪽으로 밀어도 **구분 1.09** 가 한계다
+	*                                 (시드가 이미 거의 흰색이다) ⇒ 반대로 «어둡게» 가야 갈린다
+	*   `#6A1B9A` 시드 + 다크 바탕 → `-weak` 이 바탕 쪽으로는 그래픽 3.0 을 못 낸다
+	*
+	* ⇒ 한 방향을 시도하고 실패하면 **반대 방향**을 본다. 두 방향 다 실패하는 것만 극단값으로
+	*   떨어뜨린다.
+	*/
+	const either = (from, ok, first, second) => towards(from, first, ok) ?? towards(from, second, ok);
+	const color = either(seed, (c) => contrast(c, pickOnColor(c)) >= 4.5, away, near) ?? seed;
+	const strongOk = (c) => contrast(c, bg) >= 4.5 && contrast(c, color) >= 1.2;
+	const strong = either(color, strongOk, away, near) ?? away;
+	let weak;
+	if (contrast(color, bg) >= 3) {
+		weak = color;
+		for (let p = 1; p >= 0; p -= STEP) {
+			const candidate = mix(color, bg, p);
+			if (contrast(candidate, bg) < 3) break;
+			weak = candidate;
+		}
+	} else weak = towards(color, away, (c) => contrast(c, bg) >= 3) ?? away;
+	return {
+		weakest: mix(weak, bg, .25),
+		weaker: mix(weak, bg, .5),
+		weak,
+		color,
+		strong,
+		txt: pickOnColor(color)
+	};
+}
+/** 램프를 커스텀 프로퍼티 이름 → 값 맵으로. */
+function accentCustomProperties(ramp, role = "primary") {
+	return {
+		[`--u-${role}-color-weakest`]: ramp.weakest,
+		[`--u-${role}-color-weaker`]: ramp.weaker,
+		[`--u-${role}-color-weak`]: ramp.weak,
+		[`--u-${role}-color`]: ramp.color,
+		[`--u-${role}-color-strong`]: ramp.strong,
+		[`--u-${role}-txt-color`]: ramp.txt
+	};
+}
+//#endregion
+export { AA_TEXT, MIN_STEP_SEPARATION, accentCustomProperties, contrast, deriveAccentRamp, luminance, mix, parseColor, pickOnColor, toHex };

package/dist/utilities/icons.js

@@ -187,7 +187,7 @@ var IconRegistry = class {
 				IconCache.set(lib, name, svg);
 				return svg;
 			} catch (error) {
-				console.error(`[IconRegistry] '${key}' 아이콘 리졸브 실패 (재시도 가능):`, error);
+				console.error(`[IconRegistry] Failed to resolve icon '${key}' (will retry):`, error);
 				return;
 			}
 		})();

package/dist/utilities/statusIcon.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 역할 축(의미)의 상태 → 내장 아이콘 이름.
+ *
+ * ## 왜 있나
+ *
+ * `u-tag`·`u-badge` 의 상태는 **색으로만** 전달돼 왔다. 색각 이상(남성 약 8%)이나 흑백
+ * 인쇄에서는 *"성공"* 과 *"실패"* 가 같은 회색 알약이 된다. 대비 계약(1.20.0)은
+ * *읽히는가* 를 지키지 *구별되는가* 를 지키지 않는다 — 역할 색 충돌 검사(ΔE)가
+ * **색 공간에서** 세운 그 구분을, 이 표는 **모양 공간에서** 세운다.
+ *
+ * ## 매핑하지 않는 것
+ *
+ * - **장식 축**(`blue`·`purple` …)은 *색 자체*를 뜻하지 의미를 뜻하지 않는다.
+ * - **`neutral`·`primary`** 는 상태가 아니다(`primary` 는 브랜드 강조이지 «좋음»이 아니다).
+ *
+ * ⇒ 그 자리에 `icon` 을 줘도 **아무것도 그리지 않는다.** 없는 의미를 아이콘으로 지어내면
+ *   그 아이콘이 잘못된 정보를 나른다.
+ *
+ * ⚠**`u-alert` 의 `status` 축(`error`·`notice` …)은 다른 어휘다** — 이름이 겹치지 않으므로
+ * 한 표로 합치지 않았다. 합치려면 두 축의 이름을 먼저 통일해야 하고, 그것은 파괴적 변경이다.
+ */
+export declare const STATUS_ICON: {
+    readonly info: "info-circle-fill";
+    readonly success: "circle-check-fill";
+    readonly warning: "alert-triangle-fill";
+    readonly danger: "alert-circle-fill";
+};
+/** 의미를 갖는 역할 값. */
+export type StatusRole = keyof typeof STATUS_ICON;
+/** 역할 값이면 아이콘 이름을, 아니면 `undefined` 를 돌려준다. */
+export declare function statusIcon(color?: string): string | undefined;