@iyulab/components 0.4.0 → 1.0.1

package/skills/iyulab-components/references/extensions/form-control.md

@@ -0,0 +1,79 @@
+# UFormControlElement\<T\>
+
+```ts
+import { UFormControlElement } from '@iyulab/components';
+```
+
+Abstract base class for all form-associated controls. Enables native `<form>` participation via the [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) API.
+
+## When to extend
+
+Use when building a custom input that should participate in forms (`formAssociated = true`), support `name`/`value` submission, and integrate with the library's validation pattern.
+
+```ts
+import { UFormControlElement } from '@iyulab/components';
+import { customElement, property } from 'lit/decorators.js';
+import { html } from 'lit';
+
+@customElement('my-input')
+export class MyInput extends UFormControlElement<string> {
+  @property() value = '';
+
+  render() {
+    return html`
+      <input
+        .value=${this.value}
+        ?disabled=${this.disabled}
+        ?readonly=${this.readonly}
+        @change=${(e: Event) => {
+          this.value = (e.target as HTMLInputElement).value;
+          this.fire('change');
+        }}
+      />
+    `;
+  }
+
+  validate(): boolean {
+    if (this.required && !this.value) {
+      this.invalid = true;
+      return false;
+    }
+    this.invalid = false;
+    return true;
+  }
+
+  reset(): void {
+    this.value = '';
+    this.invalid = false;
+  }
+}
+```
+
+## Inherited Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `name` | `string` | — | — | Form field name |
+| `value` | `T` | — | — | Submitted value |
+| `disabled` | `boolean` | `false` | ✓ | Disable the control |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required field |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed state |
+| `novalidate` | `boolean` | `false` | — | Skip automatic validation |
+| `label` | `string` | — | — | Field label |
+| `description` | `string` | — | — | Helper description |
+| `validationMessage` | `string` | — | — | Custom validation error text |
+
+## Inherited Getters
+
+| Getter | Returns | Description |
+|--------|---------|-------------|
+| `form` | `HTMLFormElement \| null` | Associated form element |
+| `validity` | `ValidityState \| undefined` | Native validity state |
+
+## Abstract Methods (must implement)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `validate()` | `boolean` | Run validation logic; set `this.invalid` accordingly |
+| `reset()` | `void` | Reset value and clear validation state |

package/skills/iyulab-components/references/extensions/overlay.md

@@ -0,0 +1,76 @@
+# UOverlayElement
+
+```ts
+import { UOverlayElement } from '@iyulab/components';
+```
+
+Abstract base class for full-screen or contained overlays (dialogs, drawers, side sheets). Manages:
+
+- **Focus-trap** via `focus-trap` library
+- **Body scroll lock** while open
+- **ESC key** and **backdrop click** close
+- **OverlayManager** z-index stacking
+
+## When to extend
+
+Use when building a modal-style component that should block interaction with the rest of the page.
+
+```ts
+import { UOverlayElement } from '@iyulab/components';
+import { customElement, property } from 'lit/decorators.js';
+import { html } from 'lit';
+
+@customElement('my-modal')
+export class MyModal extends UOverlayElement {
+  @property() title = '';
+
+  render() {
+    return html`
+      <div class="backdrop" part="backdrop"></div>
+      <div class="panel" part="panel">
+        <h2>${this.title}</h2>
+        <slot></slot>
+        <button @click=${() => this.requestClose('button')}>Close</button>
+      </div>
+    `;
+  }
+}
+```
+
+## Inherited Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Open/closed state |
+| `mode` | `'modal'\|'non-modal'` | `'modal'` | ✓ | `modal` enables focus-trap |
+| `contained` | `boolean` | `false` | ✓ | Use `position: absolute` relative to parent |
+| `closeOn` | `string[]` | `['escape','backdrop','button']` | ✓ | Allowed close trigger sources |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `boolean` | Open overlay; returns `false` if cancelled |
+| `hide()` | `boolean` | Close overlay; returns `false` if cancelled |
+| `requestClose(source)` | `void` | Request close from a source string; respects `closeOn` policy |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Before overlay opens |
+| `hide` | ✓ | Before overlay closes |
+
+## Custom close policy
+
+Override `requestClose` to add custom logic before closing:
+
+```ts
+override requestClose(source: string) {
+  if (source === 'backdrop' && this.hasUnsavedChanges) {
+    // show a confirmation prompt instead
+    return;
+  }
+  super.requestClose(source);
+}
+```

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

@@ -0,0 +1,216 @@
+# Usage Guide
+
+## Installation
+
+```bash
+npm install @iyulab/components
+```
+
+---
+
+## Importing Components
+
+### All at once
+
+```ts
+import '@iyulab/components';
+```
+
+### Individual (tree-shakable)
+
+```ts
+import '@iyulab/components/dist/components/button/UButton.js';
+import '@iyulab/components/dist/components/input/UInput.js';
+```
+
+### React wrappers
+
+React wrappers are generated via `@lit/react` and live under the `react` sub-export.
+
+```ts
+import { UButton, UInput, USelect } from '@iyulab/components/react';
+```
+
+---
+
+## Theme Setup
+
+Call `Theme.init()` once at application startup (before rendering):
+
+```ts
+import { Theme } from '@iyulab/components';
+
+await Theme.init({
+  default: 'system',   // 'system' | 'light' | 'dark'
+  useBuiltIn: true,    // load bundled CSS variables (default: true)
+  store: {             // persist theme preference in localStorage (optional)
+    type: 'localStorage',
+    key: 'app-theme'
+  }
+});
+```
+
+### Switching themes at runtime
+
+```ts
+import { Theme } from '@iyulab/components';
+
+Theme.set('dark');
+Theme.set('light');
+Theme.set('system');
+
+const current = Theme.get(); // 'system' | 'light' | 'dark' | undefined
+```
+
+---
+
+## Icon Setup
+
+### Built-in icons
+
+Built-in icons are bundled at build time and served from `/assets/icons/` by default.  
+If you serve static assets from a different path, update the base URL:
+
+```ts
+import { setDefaultBaseUrl } from '@iyulab/components';
+
+setDefaultBaseUrl('/static/icons/');
+```
+
+### Using a third-party icon library
+
+Third-party libraries are loaded on-demand from CDN. Supported libraries:
+
+| `lib` value | Source | Notes |
+|---|---|---|
+| `internal` | Bundled SVGs | Default, no network |
+| `tabler` | [tabler.io/icons](https://tabler.io/icons) | `name` or `name:filled` |
+| `heroicons` | [heroicons.com](https://heroicons.com) | `name` or `name:solid` |
+| `lucide` | [lucide.dev](https://lucide.dev) | Only outline style |
+| `bootstrap` | [icons.getbootstrap.com](https://icons.getbootstrap.com) | outline / filled |
+
+```html
+<u-icon lib="tabler" name="home"></u-icon>
+<u-icon lib="tabler" name="home:filled"></u-icon>
+<u-icon lib="heroicons" name="academic-cap:solid"></u-icon>
+<u-icon lib="lucide" name="activity"></u-icon>
+```
+
+### Registering a custom icon library
+
+```ts
+import { IconRegistry } from '@iyulab/components';
+
+IconRegistry.register('my-icons', async (name) => {
+  const res = await fetch(`/icons/${name}.svg`);
+  if (!res.ok) return undefined;
+  return res.text();
+});
+```
+
+```html
+<u-icon lib="my-icons" name="logo"></u-icon>
+```
+
+### Unregistering
+
+```ts
+IconRegistry.unregister('my-icons');
+```
+
+---
+
+## CSS Custom Properties
+
+Components expose `--` CSS custom properties for visual customization. Apply them on a wrapping element or `:root`:
+
+```css
+:root {
+  --alert-background-color: #1a1a2e;
+  --spinner-indicator-color: royalblue;
+}
+
+u-button {
+  --btn-radius: 999px;
+}
+```
+
+---
+
+## CSS `part` Styling
+
+Shadow DOM internals are exposed via `::part()`:
+
+```css
+u-input::part(input) {
+  font-size: 1rem;
+  letter-spacing: 0.02em;
+}
+
+u-dialog::part(panel) {
+  border-radius: 1rem;
+  box-shadow: 0 8px 32px rgba(0,0,0,0.3);
+}
+```
+
+---
+
+## Form Integration
+
+All form control components (`u-input`, `u-select`, `u-checkbox`, etc.) use the native [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) API (`formAssociated = true`) and work inside standard `<form>` elements.
+
+```html
+<form id="my-form">
+  <u-input name="email" type="email" required></u-input>
+  <u-select name="role">
+    <u-option value="admin">Admin</u-option>
+    <u-option value="viewer">Viewer</u-option>
+  </u-select>
+  <u-button type="submit">Submit</u-button>
+</form>
+```
+
+### Validating programmatically
+
+```ts
+const input = document.querySelector('u-input');
+input.validate(); // returns boolean, sets `invalid` attribute
+input.reset();    // clears value and validation state
+```
+
+### Using `u-form` for model binding
+
+```ts
+import { UForm } from '@iyulab/components';
+
+const form = document.querySelector('u-form') as UForm;
+form.model = { email: 'user@example.com', role: 'admin' };
+
+form.addEventListener('change', () => {
+  console.log(form.model); // updated model
+});
+```
+
+---
+
+## Overlay / Dialog Utilities
+
+Open dialogs and toasts programmatically without creating elements manually:
+
+```ts
+import { Dialog, Toast } from '@iyulab/components';
+
+// Alert
+await Dialog.alert('Operation completed.');
+
+// Confirm
+const confirmed = await Dialog.confirm('Delete this item?');
+
+// Prompt
+const name = await Dialog.prompt('Enter your name:', { default: 'Alice' });
+
+// Toast
+Toast.success('Saved!');
+Toast.error('Something went wrong.', { duration: 5000 });
+Toast.message('Hello world', { position: 'bottom-center' });
+```

package/skills/iyulab-components/references/utilities/browser-storage.md

@@ -0,0 +1,54 @@
+# BrowserStorage
+
+```ts
+import { BrowserStorage } from '@iyulab/components';
+```
+
+Unified key-value storage API over `localStorage` or browser cookies.
+
+## Usage
+
+```ts
+// localStorage
+const storage = new BrowserStorage({ type: 'localStorage' });
+
+await storage.set('theme', 'dark');
+const theme = await storage.get('theme'); // 'dark'
+await storage.remove('theme');
+
+// Cookie
+const cookieStorage = new BrowserStorage({
+  type: 'cookie',
+  path: '/',
+  maxAge: 60 * 60 * 24 * 30  // 30 days
+});
+
+await cookieStorage.set('session', 'abc123');
+```
+
+## API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `set(key, value)` | `Promise<void>` | Store a string value |
+| `get(key)` | `Promise<string \| null>` | Retrieve a value |
+| `remove(key)` | `Promise<void>` | Delete a value |
+
+## Types
+
+```ts
+type BrowserStorageOptions = LocalStorageOptions | CookieOptions;
+
+interface LocalStorageOptions {
+  type: 'localStorage';
+}
+
+interface CookieOptions {
+  type: 'cookie';
+  path?: string;
+  domain?: string;
+  maxAge?: number;
+  sameSite?: 'strict' | 'lax' | 'none';
+  secure?: boolean;
+}
+```

package/skills/iyulab-components/references/utilities/converters.md

@@ -0,0 +1,42 @@
+# converters
+
+```ts
+import { arrayAttrConverter, jsonAttrConverter, booleanAttrConverter, dateAttrConverter, urlAttrConverter } from '@iyulab/components';
+```
+
+Lit `@property` attribute converter factory functions. Pass these to the `converter` option to handle non-primitive attribute types automatically.
+
+## Usage
+
+```ts
+import { property } from 'lit/decorators.js';
+import { arrayAttrConverter, jsonAttrConverter } from '@iyulab/components';
+
+class MyElement extends LitElement {
+  @property({ converter: arrayAttrConverter() })
+  tags: string[] = [];
+
+  @property({ converter: jsonAttrConverter<{ x: number }>() })
+  config?: { x: number };
+}
+```
+
+```html
+<!-- Array: comma-separated string ↔ string[] -->
+<my-element tags="a,b,c"></my-element>
+
+<!-- JSON: JSON string ↔ object -->
+<my-element config='{"x":42}'></my-element>
+```
+
+## API
+
+| Function | Converts | Description |
+|----------|----------|-------------|
+| `arrayAttrConverter(parser?, separator?)` | `string ↔ T[]` | Comma-separated (or custom separator) string to array |
+| `jsonAttrConverter(parser?)` | `string ↔ T` | JSON string to object |
+| `booleanAttrConverter()` | `string ↔ boolean` | Empty string / null to boolean |
+| `dateAttrConverter(parser?)` | `string ↔ Date` | ISO 8601 string to `Date` |
+| `urlAttrConverter(parser?)` | `string ↔ URL` | URL string to `URL` object |
+
+All converters accept an optional `parser` function for custom transformation logic.

package/skills/iyulab-components/references/utilities/dialog.md

@@ -0,0 +1,75 @@
+# Dialog (utility)
+
+```ts
+import { Dialog } from '@iyulab/components';
+```
+
+Programmatically open alert, confirm, and prompt dialogs without manually creating `u-dialog` elements.
+
+## Usage
+
+```ts
+// Alert — await until dismissed
+await Dialog.alert('Operation completed.');
+
+// Confirm — returns true/false
+const confirmed = await Dialog.confirm('Delete this item?');
+if (confirmed) deleteItem();
+
+// Prompt — returns entered string or null if cancelled
+const name = await Dialog.prompt('Enter your name:', { default: 'Alice' });
+
+// Custom dialog with action buttons
+const result = await Dialog.show({
+  title: 'Choose an option',
+  content: 'Which plan do you want?',
+  actions: [
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro', variant: 'solid' }
+  ]
+});
+// result = 'free' | 'pro' | null (if closed without selecting)
+```
+
+## API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `Dialog.alert(message, options?)` | `Promise<void>` | Informational alert |
+| `Dialog.confirm(message, options?)` | `Promise<boolean>` | Confirm / Cancel dialog |
+| `Dialog.prompt(message, options?)` | `Promise<string \| null>` | Text input dialog |
+| `Dialog.show(options)` | `Promise<string \| null>` | Custom dialog; resolves with clicked action `value` |
+
+## Types
+
+```ts
+interface DialogOptions {
+  target?: HTMLElement;
+  title?: string;
+  closable?: boolean;
+  placement?: DialogPlacement;
+}
+
+interface ConfirmDialogOptions extends DialogOptions {
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+interface PromptDialogOptions extends DialogOptions {
+  default?: string;
+  placeholder?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+interface CustomDialogOptions extends DialogOptions {
+  content?: string | HTMLElement | TemplateResult;
+  actions?: DialogAction[];
+}
+
+interface DialogAction {
+  label: string;
+  value: string;
+  variant?: ButtonVariant;
+}
+```

package/skills/iyulab-components/references/utilities/elements.md

@@ -0,0 +1,55 @@
+# elements
+
+```ts
+import { getParentElement, querySelectorWithin, querySelectorAllWithin, buildElementHTML } from '@iyulab/components';
+```
+
+Shadow-DOM-aware DOM utility helpers.
+
+## Functions
+
+### `getParentElement(element)`
+
+Traverses up the DOM, crossing shadow root boundaries.  
+Returns the host element of a shadow root when the parent is a `ShadowRoot`.
+
+```ts
+const parent = getParentElement(myElement);
+```
+
+---
+
+### `querySelectorWithin(element, selector)`
+
+Queries within the same root (shadow root or document) as `element`.  
+Avoids leaking queries across shadow boundaries.
+
+```ts
+const btn = querySelectorWithin(this, '#submit');
+```
+
+---
+
+### `querySelectorAllWithin(element, selector)`
+
+Same as `querySelectorWithin` but returns all matches.
+
+```ts
+const inputs = querySelectorAllWithin(this, 'u-input');
+```
+
+---
+
+### `buildElementHTML(tag, attrs, content?)`
+
+Builds an XSS-safe custom element HTML string. All attribute values and content are sanitized.
+
+```ts
+const html = buildElementHTML('u-alert', {
+  status: 'success',
+  open: '',
+}, 'File saved.');
+// → '<u-alert status="success" open="">File saved.</u-alert>'
+```
+
+> Use this when dynamically constructing HTML strings for `innerHTML` or server-side rendering.

package/skills/iyulab-components/references/utilities/icons.md

@@ -0,0 +1,53 @@
+# IconRegistry
+
+```ts
+import { IconRegistry, getDefaultBaseUrl, setDefaultBaseUrl } from '@iyulab/components';
+```
+
+Manages icon library resolvers. Built-in libraries (`internal`, `tabler`, `heroicons`, `lucide`, `bootstrap`) are pre-registered.
+
+## Base URL
+
+Icons served from the file system use a configurable base path (default: `/assets/icons/`).
+
+```ts
+setDefaultBaseUrl('/static/icons/');  // change base URL
+getDefaultBaseUrl();                  // get current base URL
+```
+
+## Register a custom library
+
+```ts
+IconRegistry.register('my-icons', async (name: string) => {
+  const res = await fetch(`/icons/${name}.svg`);
+  return res.ok ? res.text() : undefined;
+});
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `IconRegistry.register(lib, resolver)` | Register an icon library |
+| `IconRegistry.unregister(lib)` | Remove a library |
+| `IconRegistry.has(lib)` | Check if a library is registered |
+| `IconRegistry.resolve(lib, name)` | `Promise<string \| undefined>` — resolve SVG source |
+
+## Built-in Libraries
+
+| `lib` | Style variants | CDN version |
+|-------|----------------|-------------|
+| `internal` | (bundled) | — |
+| `tabler` | `name` / `name:filled` | 3.40.0 |
+| `heroicons` | `name` / `name:solid` | 2.2.0 |
+| `lucide` | `name` | 0.503.0 |
+| `bootstrap` | `name` / `name:filled` | 1.11.3 |
+
+## Caching
+
+Resolved SVGs are cached by `lib:name` key. The cache persists for the lifetime of the page.
+
+```ts
+// Internal cache is managed automatically; manual access is rarely needed.
+// IconCache.clear(); // clears all cached entries
+```

package/skills/iyulab-components/references/utilities/overlay-manager.md

@@ -0,0 +1,34 @@
+# OverlayManager
+
+```ts
+import { OverlayManager } from '@iyulab/components';
+```
+
+Internal static manager for the overlay stack. Used by `UOverlayElement` (`u-dialog`, `u-drawer`) to track open overlays, assign z-index, and manage body scroll locking.
+
+> **Note:** You generally do not need to use `OverlayManager` directly. It is called automatically by overlay components. Only use it if you are building a custom overlay component that extends `UOverlayElement`.
+
+## API
+
+| Member | Type / Returns | Description |
+|--------|----------------|-------------|
+| `OverlayManager.add(overlay, lockBody?)` | `void` | Register an overlay; increments z-index; optionally locks body scroll |
+| `OverlayManager.remove(overlay, lockBody?)` | `void` | Unregister an overlay; releases scroll lock if no overlays remain |
+| `OverlayManager.isTopmost(overlay)` | `boolean` | Returns `true` if the overlay is the topmost in the stack (used for ESC key handling) |
+| `OverlayManager.size` | `number` | Number of currently open overlays |
+| `OverlayManager.trapStack` | `FocusTrap[]` | Shared focus-trap stack (used internally by focus-trap library) |
+
+## Example (custom overlay)
+
+```ts
+import { UOverlayElement } from '@iyulab/components';
+
+class MyOverlay extends UOverlayElement {
+  // UOverlayElement already calls OverlayManager.add/remove internally
+  // Override requestClose() if you need custom close logic
+  override requestClose(source: string) {
+    if (source === 'backdrop' && this.hasUnsavedChanges) return;
+    super.requestClose(source);
+  }
+}
+```