@iyulab/components 0.4.0 → 1.0.1

package/dist/utilities/sanitizers.js

@@ -1,43 +1,75 @@
+//#region src/utilities/sanitizers.ts
+/**
+* HTML 출력 시 XSS 방지를 위한 escape 유틸
+*
+* 컨텍스트에 맞는 함수를 사용해야 합니다.
+*
+* - escapeHtmlText : HTML 텍스트 노드에 삽입할 때
+* - escapeHtmlAttr : HTML attribute 값에 삽입할 때
+* - escapeHtmlHref : href/src 같은 URL attribute에 삽입할 때
+*/
+/**
+* Zero Width Space / LTR / RTL mark / BOM 등
+* 화면에 표시되지 않는 유니코드 문자를 제거합니다.
+*/
 function stripZeroWidth(value) {
-  const ZERO_WIDTH_REGEX = /[\u200B\u200C\u200D\u200E\u200F\uFEFF]/g;
-  return ZERO_WIDTH_REGEX.test(value) ? value.replace(ZERO_WIDTH_REGEX, "") : value;
+	const ZERO_WIDTH_REGEX = /[\u200B\u200C\u200D\u200E\u200F\uFEFF]/g;
+	return ZERO_WIDTH_REGEX.test(value) ? value.replace(ZERO_WIDTH_REGEX, "") : value;
 }
-const HTML_TEXT_ESCAPE_REGEX = /[&<>"']/g;
-const HTML_TEXT_ESCAPE_MAP = {
-  "&": "&amp;",
-  "<": "&lt;",
-  ">": "&gt;",
-  '"': "&quot;",
-  "'": "&#39;"
+/** HTML text context escape 대상 문자 */
+var HTML_TEXT_ESCAPE_REGEX = /[&<>"']/g;
+/** HTML text context escape용 문자 매핑 */
+var HTML_TEXT_ESCAPE_MAP = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&#39;"
 };
+/**
+* HTML 텍스트 노드(context)에 삽입할 문자열을 escape합니다.
+*
+* 예:
+*   <script> → &lt;script&gt;
+*/
 function escapeHtmlText(value) {
-  return HTML_TEXT_ESCAPE_REGEX.test(value) ? value.replace(HTML_TEXT_ESCAPE_REGEX, (ch) => HTML_TEXT_ESCAPE_MAP[ch]) : value;
+	return HTML_TEXT_ESCAPE_REGEX.test(value) ? value.replace(HTML_TEXT_ESCAPE_REGEX, (ch) => HTML_TEXT_ESCAPE_MAP[ch]) : value;
 }
-const HTML_ATTR_ESCAPE_REGEX = /[&<>"]/g;
-const HTML_ATTR_ESCAPE_MAP = {
-  "&": "&amp;",
-  "<": "&lt;",
-  ">": "&gt;",
-  '"': "&quot;"
+/** HTML attribute escape 대상 문자 */
+var HTML_ATTR_ESCAPE_REGEX = /[&<>"]/g;
+/** HTML attribute escape용 문자 매핑 */
+var HTML_ATTR_ESCAPE_MAP = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
 };
+/**
+* HTML attribute 값(context)에 삽입할 문자열을 escape합니다.
+* 
+* 예:
+*   <div title="{value}">
+*/
 function escapeHtmlAttr(value) {
-  return HTML_ATTR_ESCAPE_REGEX.test(value) ? value.replace(HTML_ATTR_ESCAPE_REGEX, (ch) => HTML_ATTR_ESCAPE_MAP[ch]) : value;
+	return HTML_ATTR_ESCAPE_REGEX.test(value) ? value.replace(HTML_ATTR_ESCAPE_REGEX, (ch) => HTML_ATTR_ESCAPE_MAP[ch]) : value;
 }
-const HREF_STRIP_CHARS_REGEX = /[\u0000-\u001F\u007F\s]+/g;
-const HREF_UNSAFE_PROTOCOL_REGEX = /^(?:javascript|data|vbscript):/i;
+/** protocol 우회 공격 방지를 위한 공백/제어문자 제거 */
+var HREF_STRIP_CHARS_REGEX = /[\u0000-\u001F\u007F\s]+/g;
+/** href/src에서 차단해야 하는 위험 protocol */
+var HREF_UNSAFE_PROTOCOL_REGEX = /^(?:javascript|data|vbscript):/i;
+/**
+* href / src attribute용 문자열 처리
+*
+* 예:
+*  <a href="{value}">
+*/
 function escapeHtmlHref(value) {
-  let normalized = stripZeroWidth(value).trim();
-  if (HREF_STRIP_CHARS_REGEX.test(normalized)) {
-    normalized = normalized.replace(HREF_STRIP_CHARS_REGEX, "");
-  }
-  normalized = normalized.replace(/\\/g, "/");
-  if (normalized.startsWith("//")) {
-    return "#";
-  }
-  if (HREF_UNSAFE_PROTOCOL_REGEX.test(normalized)) {
-    return "#";
-  }
-  return escapeHtmlAttr(normalized);
+	let normalized = stripZeroWidth(value).trim();
+	if (HREF_STRIP_CHARS_REGEX.test(normalized)) normalized = normalized.replace(HREF_STRIP_CHARS_REGEX, "");
+	normalized = normalized.replace(/\\/g, "/");
+	if (normalized.startsWith("//")) return "#";
+	if (HREF_UNSAFE_PROTOCOL_REGEX.test(normalized)) return "#";
+	return escapeHtmlAttr(normalized);
 }
-
+//#endregion
 export { escapeHtmlAttr, escapeHtmlHref, escapeHtmlText, stripZeroWidth };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "keywords": [
     "iyulab",
     "components",
@@ -17,6 +17,9 @@
   },
   "files": [
     "dist",
+    "plugins/**/*.js",
+    "plugins/**/*.d.ts",
+    "skills",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
@@ -29,42 +32,46 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./dist/*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*"
-    }
+    "./dist/*": "./dist/*",
+    "./react": "./dist/react/index.js",
+    "./react/*": "./dist/react/*",
+    "./styles/*": "./dist/styles/*",
+    "./plugins/*": "./plugins/*"
   },
   "scripts": {
     "test": "vite --force",
-    "build": "eslint && vite build"
+    "build:plugins": "tsc -p plugins/tsconfig.json",
+    "build": "eslint && vite build && npm run build:plugins"
   },
   "dependencies": {
-    "@floating-ui/dom": "^1.7.5",
-    "lit": "^3.3.2",
-    "reflect-metadata": "^0.2.2"
+    "@floating-ui/dom": "^1.7.6",
+    "focus-trap": "^8.0.1",
+    "lit": "^3.3.2"
   },
   "peerDependencies": {
-    "@lit/react": ">=1.0.0",
+    "@lit/react": ">=1.0.8",
     "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
-    "react": {
+    "@lit/react": {
       "optional": true
     },
-    "@lit/react": {
+    "react": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.3",
-    "@types/node": "^25.3.2",
-    "eslint": "^9.39.3",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^25.5.0",
+    "eslint": "^9.39.4",
     "eslint-plugin-lit": "^2.2.1",
-    "globals": "^17.3.0",
+    "glob": "^13.0.6",
+    "globals": "^17.4.0",
+    "react": "^19.2.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vite": "^7.3.1",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
     "vite-plugin-dts": "^4.5.4",
-    "vite-plugin-static-copy": "^3.2.0"
+    "vite-plugin-static-copy": "^4.0.0"
   }
 }

package/plugins/vite-plugin-glob-resolve.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+/**
+ * Rolldown의 preserveModules 모드에서 import.meta.glob의 query 옵션 사용 시
+ * 빈 export가 생성되는 문제를 해결하는 플러그인.
+ *
+ * - `?raw`: 파일 내용을 문자열로 반환
+ * - `?inline`: 파일 내용을 문자열로 반환
+ * - `?url`: 파일을 asset으로 emit하고 URL을 반환
+ *
+ * 가상 모듈(\0 prefix)로 변환하여 파일명에 `?`가 포함되는 것을 방지합니다.
+ */
+export default function globResolve(): Plugin;

package/plugins/vite-plugin-glob-resolve.js

@@ -0,0 +1,66 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+import { createHash } from 'crypto';
+const VIRTUAL_PREFIX = '\0glob-assets';
+const SUPPORTED_QUERIES = ['?raw', '?inline', '?url'];
+function shortHash(input) {
+    return createHash('md5').update(input).digest('hex').slice(0, 8);
+}
+/**
+ * Rolldown의 preserveModules 모드에서 import.meta.glob의 query 옵션 사용 시
+ * 빈 export가 생성되는 문제를 해결하는 플러그인.
+ *
+ * - `?raw`: 파일 내용을 문자열로 반환
+ * - `?inline`: 파일 내용을 문자열로 반환
+ * - `?url`: 파일을 asset으로 emit하고 URL을 반환
+ *
+ * 가상 모듈(\0 prefix)로 변환하여 파일명에 `?`가 포함되는 것을 방지합니다.
+ */
+export default function globResolve() {
+    const idToAbsPath = new Map();
+    return {
+        name: 'vite:glob-resolve',
+        enforce: 'pre',
+        resolveId(source, importer) {
+            for (const query of SUPPORTED_QUERIES) {
+                if (source.endsWith(query)) {
+                    const rawPath = source.slice(0, -query.length);
+                    const absPath = importer
+                        ? resolve(dirname(importer), rawPath)
+                        : rawPath;
+                    const name = basename(absPath);
+                    const hash = shortHash(absPath);
+                    const queryName = query.slice(1);
+                    const virtualId = `${VIRTUAL_PREFIX}_${queryName}/${name}.${hash}`;
+                    idToAbsPath.set(virtualId, absPath);
+                    return virtualId;
+                }
+            }
+            return null;
+        },
+        load(id) {
+            if (!id.startsWith(VIRTUAL_PREFIX))
+                return null;
+            const absPath = idToAbsPath.get(id);
+            if (!absPath)
+                return null;
+            // virtualId에서 queryName 추출: "\0glob-assets_{queryName}/..."
+            const queryName = id.slice(VIRTUAL_PREFIX.length + 1).split('/')[0];
+            if (queryName === 'raw' || queryName === 'inline') {
+                const content = readFileSync(absPath, 'utf-8');
+                return `export default ${JSON.stringify(content)};`;
+            }
+            if (queryName === 'url') {
+                const source = readFileSync(absPath);
+                const fileName = basename(absPath);
+                const ref = this.emitFile({
+                    type: 'asset',
+                    name: fileName,
+                    source,
+                });
+                return `export default import.meta.ROLLUP_FILE_URL_${ref};`;
+            }
+            return null;
+        }
+    };
+}

package/plugins/vite-plugin-react-wrapper.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+interface PluginOptions {
+    /** 컴포넌트 소스 디렉토리 경로 (기본값: 'src/components') */
+    input?: string;
+    /** React 래퍼 출력 폴더 - 빌드 outDir 기준 상대 경로 (기본값: 'react') */
+    output?: string;
+}
+/**
+ * Lit Element 컴포넌트를 React 래퍼로 자동 생성하는 Vite 플러그인
+ */
+export default function reactWrapperPlugin(options: PluginOptions): Plugin;
+export {};

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

@@ -0,0 +1,206 @@
+import { resolve, join, relative, dirname, basename } from 'path';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { gzipSync } from 'zlib';
+import { globSync } from 'glob';
+/**
+ * Lit Element 컴포넌트를 React 래퍼로 자동 생성하는 Vite 플러그인
+ */
+export default function reactWrapperPlugin(options) {
+    let rootDir;
+    let buildOutDir;
+    let outDir;
+    return {
+        name: 'vite-plugin-react-wrapper',
+        configResolved(config) {
+            rootDir = config.root;
+            buildOutDir = resolve(rootDir, config.build.outDir);
+            outDir = resolve(buildOutDir, options.output || 'react');
+        },
+        closeBundle() {
+            const log = (msg) => console.log(`\x1b[36m[react-wrapper]\x1b[0m ${msg}`);
+            log('Generating React wrappers...');
+            // 컴포넌트 수집
+            const inputPattern = (options.input || 'src/components') + '/**/*.ts';
+            const files = globSync(inputPattern, { cwd: rootDir, absolute: true });
+            const components = files.flatMap((f) => parseComponent(f));
+            if (components.length === 0) {
+                log('No components found.');
+                return;
+            }
+            // 출력 디렉토리 생성
+            mkdirSync(outDir, { recursive: true });
+            // 래퍼 생성
+            const generated = [];
+            for (const comp of components) {
+                generated.push(...writeWrapper(comp, outDir, buildOutDir));
+            }
+            generated.push(...writeIndex(components, outDir, buildOutDir));
+            // 결과 출력
+            generated.sort((a, b) => a.size - b.size);
+            for (const f of generated) {
+                const kb = (f.size / 1024).toFixed(2);
+                const gzKb = (f.gzipSize / 1024).toFixed(2);
+                const pad = ' '.repeat(Math.max(0, 50 - f.path.length));
+                console.log(`${f.path}${pad}${kb.padStart(6)} kB │ gzip: ${gzKb.padStart(6)} kB`);
+            }
+            log(`Generated ${components.length} React wrappers.`);
+        }
+    };
+}
+// --- 컴포넌트 파싱 ---
+function parseComponent(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    // @customElement('tag-name') 데코레이터 확인
+    const tagMatch = content.match(/@customElement\s*\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (!tagMatch)
+        return [];
+    // export class ClassName 추출
+    const classMatch = content.match(/export\s+class\s+(\w+)/);
+    if (!classMatch)
+        return [];
+    const events = collectEvents(content);
+    return [{
+            className: classMatch[1],
+            tagName: tagMatch[1],
+            filePath,
+            events,
+        }];
+}
+function collectEvents(content) {
+    // import 구문에서 타입명 → 소스 경로 매핑 수집
+    // 예: import { ShowEventDetail } from '../../events/ShowEvent.js';
+    const typeImportMap = new Map();
+    for (const m of content.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g)) {
+        const importPath = m[2];
+        for (const name of m[1].split(',')) {
+            const typeName = name.replace(/type\s+/, '').trim();
+            if (typeName)
+                typeImportMap.set(typeName, importPath);
+        }
+    }
+    const eventMap = new Map();
+    // JSDoc @event 패턴: @event eventName
+    for (const m of content.matchAll(/@event\s+([\w-]+)/g)) {
+        if (!eventMap.has(m[1]))
+            eventMap.set(m[1], { detailType: 'unknown', importPath: '' });
+    }
+    // this.fire<DetailType>('eventName') 패턴 - 제네릭 타입 추출
+    for (const m of content.matchAll(/this\.fire\s*(?:<([^>]+)>)?\s*\(\s*['"]([\w-]+)['"]/g)) {
+        const detailType = m[1] || 'unknown';
+        const importPath = typeImportMap.get(detailType) || '';
+        eventMap.set(m[2], { detailType, importPath });
+    }
+    return Array.from(eventMap, ([name, { detailType, importPath }]) => ({
+        name,
+        reactName: toCamelEvent(name),
+        detailType,
+        importPath,
+    }));
+}
+/** kebab-case 이벤트명을 onCamelCase로 변환 (예: shift-start → onShiftStart) */
+function toCamelEvent(name) {
+    return 'on' + name.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+function writeFile(filePath, content, buildOutDir) {
+    writeFileSync(filePath, content, 'utf-8');
+    return {
+        path: relative(buildOutDir, filePath).replace(/\\/g, '/'),
+        size: Buffer.byteLength(content, 'utf-8'),
+        gzipSize: gzipSync(content).length,
+    };
+}
+function computeImportPath(from, to) {
+    let rel = relative(dirname(from), to).replace(/\\/g, '/').replace(/\.ts$/, '');
+    if (!rel.startsWith('.'))
+        rel = './' + rel;
+    return rel;
+}
+function writeWrapper(comp, outDir, buildOutDir) {
+    const { className, tagName, events } = comp;
+    const jsPath = join(outDir, `${className}.js`);
+    const dtsPath = join(outDir, `${className}.d.ts`);
+    // 소스 파일의 빌드 출력 경로 추정 (src/ → 빌드 outDir 매핑)
+    const srcIndex = comp.filePath.replace(/\\/g, '/').indexOf('/src/');
+    const relFromSrc = srcIndex >= 0
+        ? comp.filePath.substring(srcIndex + 5).replace(/\\/g, '/').replace(/\.ts$/, '')
+        : basename(comp.filePath, '.ts');
+    const builtModulePath = resolve(buildOutDir, relFromSrc + '.js');
+    const importPath = computeImportPath(jsPath, builtModulePath);
+    // events 객체 생성
+    const eventsObj = events.length > 0
+        ? `{\n${events.map(e => `    ${e.reactName}: '${e.name}',`).join('\n')}\n  }`
+        : '{}';
+    // .js
+    const js = `import React from 'react';
+import { createComponent } from '@lit/react';
+import { ${className} } from '${importPath}';
+
+export const ${className} = createComponent({
+  react: React,
+  tagName: '${tagName}',
+  elementClass: ${className},
+  events: ${eventsObj},
+});
+`;
+    // .d.ts - import 구문 생성
+    const dtsImportPath = importPath.replace(/\.js$/, '');
+    const dtsImports = [
+        `import React from 'react';`,
+        `import { ${className} as ${className}Element } from '${dtsImportPath}';`,
+    ];
+    // 이벤트 detail 타입별 import - 소스 원본 경로 기준으로 빌드 경로 계산
+    const srcDir = dirname(comp.filePath);
+    const detailImportMap = new Map(); // 빌드경로 → [타입명]
+    for (const e of events) {
+        if (e.detailType === 'unknown' || !e.importPath)
+            continue;
+        // 소스 상대경로를 절대경로로 변환 후 빌드 경로 계산
+        const absEventSrc = resolve(srcDir, e.importPath).replace(/\\/g, '/');
+        const eventSrcIndex = absEventSrc.indexOf('/src/');
+        const relFromSrc = eventSrcIndex >= 0
+            ? absEventSrc.substring(eventSrcIndex + 5).replace(/\.js$/, '')
+            : '';
+        if (!relFromSrc)
+            continue;
+        const absEventBuilt = resolve(buildOutDir, relFromSrc);
+        const eventImportPath = computeImportPath(dtsPath, absEventBuilt + '.js').replace(/\.js$/, '');
+        const types = detailImportMap.get(eventImportPath) || [];
+        if (!types.includes(e.detailType))
+            types.push(e.detailType);
+        detailImportMap.set(eventImportPath, types);
+    }
+    for (const [path, types] of detailImportMap) {
+        dtsImports.push(`import { type ${types.join(', type ')} } from '${path}';`);
+    }
+    const eventTypes = events.length > 0
+        ? events.map(e => {
+            const type = e.detailType !== 'unknown' ? `CustomEvent<${e.detailType}>` : 'CustomEvent';
+            return `  ${e.reactName}?: (event: ${type}) => void;`;
+        }).join('\n') + '\n'
+        : '';
+    const dts = `${dtsImports.join('\n')}
+
+export declare const ${className}: React.ForwardRefExoticComponent<
+  Partial<${className}Element> & React.HTMLAttributes<${className}Element> & {
+${eventTypes}  }
+>;
+
+export type ${className}Props = React.ComponentProps<typeof ${className}>;
+`;
+    return [
+        writeFile(jsPath, js, buildOutDir),
+        writeFile(dtsPath, dts, buildOutDir),
+    ];
+}
+function writeIndex(components, outDir, buildOutDir) {
+    const jsExports = components
+        .map(c => `export { ${c.className} } from './${c.className}.js';`)
+        .join('\n');
+    const dtsExports = components
+        .map(c => `export { ${c.className}, ${c.className}Props } from './${c.className}';`)
+        .join('\n');
+    return [
+        writeFile(join(outDir, 'index.js'), jsExports + '\n', buildOutDir),
+        writeFile(join(outDir, 'index.d.ts'), dtsExports + '\n', buildOutDir),
+    ];
+}

package/skills/iyulab-components/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: iyulab-components
+description: Web component library built on Lit. Covers all u-* custom elements (buttons, forms, overlays, navigation, data display), utilities (Theme, Toast, Dialog, icons), and base classes for extension. Use when working with @iyulab/components package.
+license: MIT
+metadata:
+  author: iyulab
+  version: "1.0.1"
+---
+
+# @iyulab/components
+
+Web component library built on [Lit](https://lit.dev/). All components are custom elements (`u-*` tags) that work in any framework or vanilla HTML.
+
+## Quick Start
+
+Install the package:
+
+```bash
+npm install @iyulab/components
+```
+
+Initialize theme and import all components:
+
+```ts
+import { Theme } from '@iyulab/components';
+import '@iyulab/components'; // registers all u-* custom elements
+
+await Theme.init(); // optional — applies system/light/dark theme
+```
+
+Import individual components (tree-shakable):
+
+```ts
+import '@iyulab/components/dist/components/button/UButton.js';
+import '@iyulab/components/dist/components/input/UInput.js';
+```
+
+React wrappers (requires `@lit/react`):
+
+```ts
+import { UButton, UInput } from '@iyulab/components/react';
+```
+
+> For detailed guidance on theming, icon setup, and advanced usage, see [./references/usage.md](./references/usage.md).
+
+---
+
+## Components
+
+### Feedback
+
+- [`u-alert`](./references/components/alert.md) — Closable message banner with status variants and auto-dismiss
+- [`u-spinner`](./references/components/spinner.md) — Animated loading indicator
+- [`u-skeleton`](./references/components/skeleton.md) — Placeholder shape shown while content loads
+- [`u-progress-bar`](./references/components/progress-bar.md) — Linear progress indicator with buffer and segment support
+- [`u-progress-ring`](./references/components/progress-ring.md) — Circular progress indicator
+
+### Buttons & Actions
+
+- [`u-button`](./references/components/button.md) — Versatile button with multiple variants; renders as `<a>` when `href` is set
+- [`u-icon-button`](./references/components/icon-button.md) — Square icon-only button with built-in tooltip
+- [`u-button-group`](./references/components/button-group.md) — Groups buttons with shared variant and disabled state
+
+### Form Controls
+
+- [`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-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
+- [`u-slider`](./references/components/slider.md) — Range slider; single-thumb or dual-thumb (range) mode
+- [`u-rating`](./references/components/rating.md) — Star/custom-symbol rating input
+- [`u-field`](./references/components/field.md) — Layout wrapper providing label, description, and validation message
+- [`u-form`](./references/components/form.md) — Form group with two-way model binding and validation
+- [`u-option`](./references/components/option.md) — Selectable option item for `u-select`, `u-radio`, `u-input`
+
+### Overlay & Floating
+
+- [`u-dialog`](./references/components/dialog.md) — Modal/non-modal dialog with configurable placement
+- [`u-drawer`](./references/components/drawer.md) — Side-panel that slides in from any edge
+- [`u-popover`](./references/components/popover.md) — Anchored floating panel with flexible trigger/dismiss policies
+- [`u-tooltip`](./references/components/tooltip.md) — Hover/focus tooltip anchored to a target element
+
+### Navigation
+
+- [`u-breadcrumb`](./references/components/breadcrumb.md) — Hierarchical location indicator
+- [`u-breadcrumb-item`](./references/components/breadcrumb.md) — Individual breadcrumb link/label
+- [`u-menu`](./references/components/menu.md) — Menu container with keyboard navigation and selection modes
+- [`u-menu-item`](./references/components/menu.md) — Menu entry with optional sub-menu
+- [`u-tab-panel`](./references/components/tab-panel.md) — Tab-based content switcher
+- [`u-tab`](./references/components/tab-panel.md) — Individual tab button used inside `u-tab-panel`
+- [`u-tree`](./references/components/tree.md) — Hierarchical tree with select, check, and drag-and-drop
+- [`u-tree-item`](./references/components/tree.md) — Individual node inside `u-tree`
+
+### Layout & Display
+
+- [`u-card`](./references/components/card.md) — Content card with media, header, and footer slots
+- [`u-carousel`](./references/components/carousel.md) — Slide carousel with autoplay, navigation, and pagination
+- [`u-split-panel`](./references/components/split-panel.md) — Resizable two-panel layout
+- [`u-panel`](./references/components/panel.md) — General-purpose content panel with optional collapsing
+- [`u-divider`](./references/components/divider.md) — Horizontal or vertical separator line
+
+### Data Display
+
+- [`u-avatar`](./references/components/avatar.md) — User avatar with image, initials, or custom slot
+- [`u-badge`](./references/components/badge.md) — Status badge; can be anchored on top of other elements
+- [`u-chip`](./references/components/chip.md) — Selectable/removable chip tag
+- [`u-tag`](./references/components/tag.md) — Non-interactive label tag
+- [`u-icon`](./references/components/icon.md) — SVG icon from built-in or external icon library
+
+---
+
+## Utilities
+
+- [`Theme`](./references/utilities/theme.md) — Apply and manage light/dark/system theme
+- [`Toast`](./references/utilities/toast.md) — Programmatically show toast notifications
+- [`Dialog`](./references/utilities/dialog.md) — Programmatically show alert/confirm/prompt dialogs
+- [`IconRegistry`](./references/utilities/icons.md) — Register and resolve icon libraries
+- [`BrowserStorage`](./references/utilities/browser-storage.md) — Unified localStorage / Cookie API
+- [`converters`](./references/utilities/converters.md) — Lit property attribute converters (array, JSON, date, url…)
+- [`sanitizers`](./references/utilities/sanitizers.md) — XSS-safe HTML/URL escape helpers
+- [`elements`](./references/utilities/elements.md) — Shadow-DOM-aware DOM query helpers
+- [`OverlayManager`](./references/utilities/overlay-manager.md) — Internal overlay stack and z-index manager
+
+---
+
+## Extensions
+
+`@iyulab/components` exposes abstract base classes you can extend to build custom components that integrate seamlessly with the library's patterns (form association, overlays, floating positioning, etc.).
+
+> See [./references/extensions/](./references/extensions/) for per-class details.
+
+- [`UElement`](./references/extensions/element.md) — Root base for all components; provides `fire()`, `relay()`, `replace()` helpers
+- [`UFormControlElement<T>`](./references/extensions/form-control.md) — Base for form-associated controls; handles `disabled`, `readonly`, `invalid`, validation lifecycle
+- [`UFloatingElement`](./references/extensions/floating.md) — Base for anchored floating UI (popover, tooltip); wraps `@floating-ui/dom`
+- [`UOverlayElement`](./references/extensions/overlay.md) — Base for full-screen overlays (dialog, drawer); manages focus-trap, scroll-lock, ESC/backdrop close
+- [`UDataElement`](./references/extensions/data.md) — Base for data-driven components; auto-loads JSON from inline `<script type="application/json">`