@iyulab/components 0.3.0 → 1.0.0

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

@@ -0,0 +1,128 @@
+# u-tree / u-tree-item
+
+```ts
+import '@iyulab/components/dist/components/tree/UTree.js';
+import '@iyulab/components/dist/components/tree-item/UTreeItem.js';
+```
+
+**Tags:** `u-tree`, `u-tree-item`
+
+Hierarchical tree with support for selection, checkboxes, cascade check, and drag-and-drop.
+
+```html
+<u-tree selectable checkable check-cascade>
+  <u-tree-item value="root" expanded>
+    Root
+    <u-tree-item value="child1">Child 1</u-tree-item>
+    <u-tree-item value="child2">
+      Child 2
+      <u-tree-item value="leaf1">Leaf</u-tree-item>
+    </u-tree-item>
+  </u-tree-item>
+</u-tree>
+```
+
+---
+
+## u-tree
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-tree-item` elements |
+| `expand-icon` | Custom expand icon |
+| `collapse-icon` | Custom collapse icon |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `selectable` | `boolean` | `false` | ✓ | Enable item selection |
+| `selectMultiple` | `boolean` | `false` | ✓ | Allow multiple items selected |
+| `selectLeaf` | `boolean` | `false` | ✓ | Only leaf nodes are selectable |
+| `checkable` | `boolean` | `false` | ✓ | Show checkboxes |
+| `checkCascade` | `boolean` | `false` | ✓ | Parent/child checkbox cascade |
+| `draggable` | `boolean` | `false` | ✓ | Enable drag |
+| `droppable` | `boolean` | `false` | ✓ | Enable drop |
+| `trigger` | `'item'\|'icon'` | `'item'` | — | Click target to expand/collapse |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when selection or check state changes |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `expandAll()` | Expand all items |
+| `collapseAll()` | Collapse all items |
+| `expand(value)` | Expand item by value |
+| `collapse(value)` | Collapse item by value |
+| `toggle(value)` | Toggle item by value |
+| `getItem(value)` | Get `UTreeItem` by value |
+| `getItems(fn)` | Get items matching a filter function |
+| `mapItems(fn)` | Apply a function to all items |
+
+### CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--tree-indent-size` | Indentation per depth level |
+| `--tree-indent-guide-offset` | Guide line offset |
+| `--tree-indent-guide-width` | Guide line width |
+| `--tree-indent-guide-style` | Guide line CSS border-style |
+| `--tree-indent-guide-color` | Guide line color |
+
+---
+
+## u-tree-item
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Leading content |
+| *(default)* | Item label |
+| `suffix` | Trailing content |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | `''` | — | Unique identifier |
+| `disabled` | `boolean` | `false` | ✓ | Disable the item |
+| `expanded` | `boolean` | `false` | ✓ | Show children |
+| `selectable` | `boolean` | `false` | ✓ | This item can be selected |
+| `checkable` | `boolean` | `false` | ✓ | Show checkbox |
+| `loading` | `boolean` | `false` | ✓ | Loading state (async children) |
+| `draggable` | `boolean` | `false` | ✓ | Draggable |
+| `droppable` | `boolean` | `false` | ✓ | Accepts drops |
+| `trigger` | `'item'\|'icon'` | `'item'` | — | Expand trigger target |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `expand` | Item is expanded |
+| `collapse` | Item is collapsed |
+| `pick` | Item is selected |
+| `check` | Item checkbox toggled |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `expand()` | `boolean` | Expand this item |
+| `collapse()` | `boolean` | Collapse this item |
+| `toggle()` | `boolean` | Toggle expand/collapse |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `header` | Item header row (icon + label + suffix) |
+| `content` | Label content area |
+| `subtree` | Children container |

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

@@ -0,0 +1,60 @@
+# UDataElement
+
+```ts
+import { UDataElement } from '@iyulab/components';
+```
+
+Base class for data-driven components that load their initial data from an inline `<script type="application/json">` tag in the light DOM.
+
+## When to extend
+
+Use when you want to declare component data directly in HTML without JavaScript, or when server-rendering initial state into the page.
+
+```ts
+import { UDataElement } from '@iyulab/components';
+import { customElement } from 'lit/decorators.js';
+import { html } from 'lit';
+
+@customElement('my-list')
+export class MyList extends UDataElement {
+  private items: string[] = [];
+
+  protected override async load(data?: unknown) {
+    if (Array.isArray(data)) {
+      this.items = data as string[];
+    }
+  }
+
+  render() {
+    return html`
+      <ul>${this.items.map(i => html`<li>${i}</li>`)}</ul>
+    `;
+  }
+}
+```
+
+```html
+<my-list>
+  <script type="application/json">
+    ["Item A", "Item B", "Item C"]
+  </script>
+</my-list>
+```
+
+## Static Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `buildHTML(json, attrs?)` | `string` | Build a safe inline HTML string with JSON data embedded in a `<script type="application/json">` child |
+
+```ts
+const html = MyList.buildHTML(['Item A', 'Item B'], { class: 'my-list' });
+// → '<my-list class="my-list"><script type="application/json">["Item A","Item B"]</script></my-list>'
+```
+
+## Protected Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `load(data?)` | `Promise<void>` | Called with the parsed JSON data after the element connects; override to handle data |
+| `error(error)` | `Promise<void>` | Called when JSON parsing fails; override to handle errors |

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

@@ -0,0 +1,57 @@
+# UElement
+
+```ts
+import { UElement } from '@iyulab/components';
+```
+
+Root base class for all `@iyulab/components` components. Extends `LitElement` with event helpers and render utilities.
+
+## When to extend
+
+Extend `UElement` for any custom component that doesn't need form association or overlay/floating behavior.
+
+```ts
+import { UElement } from '@iyulab/components';
+import { customElement, property } from 'lit/decorators.js';
+import { html } from 'lit';
+
+@customElement('my-badge')
+export class MyBadge extends UElement {
+  @property() label = '';
+
+  render() {
+    return html`<span>${this.label}</span>`;
+  }
+}
+```
+
+## Protected API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `fire` | `fire<T>(name, options?): boolean` | Dispatch a `CustomEvent` on the host. `bubbles`, `composed`, `cancelable` are `true` by default. Returns `false` if the event was cancelled. |
+| `relay` | `relay(event, options?): void` | Re-dispatch a native DOM event from the host (stops original event, re-fires as new). Useful for surfacing inner element events to light DOM. |
+| `replace` | `replace(value, options?): void` | Replace the entire shadow DOM render output with a new Lit `TemplateResult`. Preserves `<style>` tags. |
+
+## Static members
+
+| Member | Description |
+|--------|-------------|
+| `styles` | Base styles (`CSSResult`); combine with `[super.styles, myStyles]` |
+| `define(name)` | Register this class as a custom element under a given tag name |
+| `dependencies` | `Record<string, typeof UElement>` — declare sub-components to auto-define |
+
+## Example: custom event
+
+```ts
+@customElement('my-input')
+class MyInput extends UElement {
+  private handleChange(e: Event) {
+    // relay native input event from shadow DOM to host
+    this.relay(e);
+
+    // or fire a custom event
+    this.fire('my-change', { detail: { value: (e.target as HTMLInputElement).value } });
+  }
+}
+```

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

@@ -0,0 +1,60 @@
+# UFloatingElement
+
+```ts
+import { UFloatingElement } from '@iyulab/components';
+```
+
+Abstract base class for anchored floating elements (tooltips, popovers, dropdowns). Wraps [`@floating-ui/dom`](https://floating-ui.com/) for automatic positioning.
+
+## When to extend
+
+Use when building a component that floats relative to a `for` target element with auto-placement, shift, and arrow support.
+
+```ts
+import { UFloatingElement } from '@iyulab/components';
+import { customElement } from 'lit/decorators.js';
+import { html } from 'lit';
+
+@customElement('my-dropdown')
+export class MyDropdown extends UFloatingElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+```
+
+```html
+<button id="btn">Open</button>
+<my-dropdown for="#btn" placement="bottom" trigger="click" shift>
+  Dropdown content
+</my-dropdown>
+```
+
+## Inherited Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Visibility state |
+| `disabled` | `boolean` | `false` | ✓ | Prevent opening |
+| `for` | `string` | — | ✓ | CSS selector for the anchor element |
+| `strategy` | `'absolute'\|'fixed'` | `'absolute'` | — | CSS positioning strategy |
+| `placement` | `Placement` | — | — | Preferred placement from `@floating-ui/dom` |
+| `offset` | `OffsetOptions` | `0` | — | Distance from anchor |
+| `shift` | `boolean` | `false` | — | Shift to stay within viewport |
+| `arrow` | `boolean` | `false` | — | Show pointing arrow |
+| `showDelay` | `number` | `0` | — | Open delay (ms) |
+| `hideDelay` | `number` | `0` | — | Close delay (ms) |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show(target?)` | `Promise<boolean>` | Open and position the floating element; returns `false` if cancelled |
+| `hide()` | `void` | Close the floating element |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Before opening |
+| `hide` | ✓ | Before closing |

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' });
+```