@iyulab/components 0.4.0 → 1.0.0

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

@@ -0,0 +1,81 @@
+# u-switch
+
+```ts
+import '@iyulab/components/dist/components/switch/USwitch.js';
+```
+
+**Tag:** `u-switch`
+
+Toggle switch (on/off). Supports custom track and thumb content via slots. Form-associated.
+
+```html
+<u-switch name="notifications" checked>Enable notifications</u-switch>
+
+<!-- Custom track labels -->
+<u-switch name="mode">
+  <span slot="track-checked">ON</span>
+  <span slot="track-unchecked">OFF</span>
+  Dark mode
+</u-switch>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Label text |
+| `track-checked` | Content inside the track when checked |
+| `track-unchecked` | Content inside the track when unchecked |
+| `thumb-checked` | Thumb content when checked |
+| `thumb-unchecked` | Thumb content when unchecked |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `checked` | `boolean` | `false` | ✓ | On/off state |
+| `disabled` | `boolean` | `false` | ✓ | Disable |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed |
+| `name` | `string` | — | — | Form field name |
+| `value` | `string` | — | — | Submitted value |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when checked state changes |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `validate()` | Validate; sets `invalid` |
+| `reset()` | Reset state |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `wrapper` | Outer layout wrapper |
+| `track` | Track element |
+| `thumb` | Thumb element |
+| `label` | Label text wrapper |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--switch-track-width` | Track width |
+| `--switch-track-height` | Track height |
+| `--switch-track-color` | Track color (unchecked) |
+| `--switch-track-color-checked` | Track color (checked) |
+| `--switch-thumb-size` | Thumb diameter |
+| `--switch-thumb-offset` | Thumb padding from track edge |
+| `--switch-thumb-color` | Thumb color (unchecked) |
+| `--switch-thumb-color-checked` | Thumb color (checked) |
+| `--switch-radius` | Track border radius |
+| `--switch-duration` | Transition animation duration |

package/skills/iyulab-components/references/components/tab-panel.md

@@ -0,0 +1,93 @@
+# u-tab-panel / u-tab
+
+```ts
+import '@iyulab/components/dist/components/tab-panel/UTabPanel.js';
+import '@iyulab/components/dist/components/tab/UTab.js';
+import '@iyulab/components/dist/components/panel/UPanel.js';
+```
+
+**Tags:** `u-tab-panel`, `u-tab`
+
+Tab-based content switcher. Pair each `u-tab` with a `u-panel` of the same `value`.
+
+```html
+<u-tab-panel value="home">
+  <u-tab value="home">Home</u-tab>
+  <u-tab value="profile">Profile</u-tab>
+  <u-tab value="settings">Settings</u-tab>
+
+  <u-panel value="home">Home content</u-panel>
+  <u-panel value="profile">Profile content</u-panel>
+  <u-panel value="settings">Settings content</u-panel>
+</u-tab-panel>
+
+<!-- Card variant, right placement, editable -->
+<u-tab-panel variant="card" placement="left" editable draggable>
+  <u-tab value="a" removable>Tab A</u-tab>
+  <u-panel value="a">Panel A</u-panel>
+</u-tab-panel>
+```
+
+---
+
+## u-tab-panel
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-tab` and `u-panel` elements |
+| `toolbar` | Toolbar area at the end of the tab bar |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | `''` | ✓ | Currently active tab value |
+| `variant` | `'line'\|'card'\|'pill'\|'plain'` | `'line'` | ✓ | Tab bar style |
+| `placement` | `'top'\|'bottom'\|'left'\|'right'` | `'top'` | ✓ | Tab bar position |
+| `editable` | `boolean` | `false` | ✓ | Allow adding/removing tabs |
+| `draggable` | `boolean` | `false` | ✓ | Allow reordering tabs by drag |
+| `disabled` | `boolean` | `false` | ✓ | Disable all tabs |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `header` | Tab bar row |
+| `nav` | Tab navigation container |
+| `toolbar` | Toolbar slot area |
+| `content` | Panel content area |
+
+---
+
+## u-tab
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Leading content |
+| *(default)* | Tab label |
+| `suffix` | Trailing content |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | `''` | ✓ | Matches a `u-panel` with the same `value` |
+| `disabled` | `boolean` | `false` | ✓ | Disable the tab |
+| `removable` | `boolean` | `false` | ✓ | Show close/remove button |
+| `draggable` | `boolean` | `false` | ✓ | Allow dragging to reorder |
+
+### Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `remove` | ✓ | Fires when the remove button is clicked |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `remove-btn` | Remove button |

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

@@ -0,0 +1,55 @@
+# u-tag
+
+```ts
+import '@iyulab/components/dist/components/tag/UTag.js';
+```
+
+**Tag:** `u-tag`
+
+Non-interactive label tag for categories, status, or metadata display.
+
+```html
+<u-tag>Default</u-tag>
+<u-tag color="blue" variant="outlined">TypeScript</u-tag>
+<u-tag color="green" rounded>Active</u-tag>
+
+<!-- With icon prefix -->
+<u-tag color="red">
+  <u-icon slot="prefix" lib="tabler" name="alert-circle"></u-icon>
+  Error
+</u-tag>
+```
+
+For interactive chips (selectable/removable), use [`u-chip`](./chip.md) instead.
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Leading content |
+| *(default)* | Tag label |
+| `suffix` | Trailing content |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'` | `'filled'` | ✓ | Visual style |
+| `color` | `'neutral'\|'blue'\|'green'\|'yellow'\|'red'\|'orange'\|'teal'\|'cyan'\|'purple'\|'pink'` | `'neutral'` | ✓ | Color |
+| `rounded` | `boolean` | `false` | ✓ | Pill shape |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `content` | Inner content wrapper |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--tag-color` | Text color |
+| `--tag-bg-color` | Background color |
+| `--tag-border-color` | Border color |

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

@@ -0,0 +1,67 @@
+# u-textarea
+
+```ts
+import '@iyulab/components/dist/components/textarea/UTextarea.js';
+```
+
+**Tag:** `u-textarea`
+
+Multi-line text input with auto-resize and optional character counter. Form-associated.
+
+```html
+<u-textarea name="bio" placeholder="Tell us about yourself" auto-resize></u-textarea>
+
+<!-- With counter and max length -->
+<u-textarea name="comment" maxlength="500" counter min-rows="3" max-rows="8">
+</u-textarea>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | — | — | Current text value |
+| `variant` | `'outlined'\|'filled'\|'underlined'\|'borderless'` | `'outlined'` | ✓ | Visual style |
+| `resize` | `'none'\|'vertical'\|'horizontal'\|'both'\|'auto'` | `'auto'` | ✓ | Resize behavior |
+| `minRows` | `number` | — | — | Minimum visible rows |
+| `maxRows` | `number` | — | — | Maximum rows (auto-resize cap) |
+| `counter` | `boolean` | `false` | ✓ | Show character counter |
+| `minlength` | `number` | — | — | Minimum character count |
+| `maxlength` | `number` | — | — | Maximum character count |
+| `placeholder` | `string` | — | — | Placeholder text |
+| `autofocus` | `boolean` | `false` | — | Auto-focus on render |
+| `autocomplete` | `AutoFill` | — | — | Browser autocomplete |
+| `spellcheck` | `boolean` | `false` | — | Spellcheck |
+| `disabled` | `boolean` | `false` | ✓ | Disable |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed |
+| `name` | `string` | — | — | Form field name |
+| `label` | `string` | — | — | Field label |
+| `description` | `string` | — | — | Helper text |
+| `validationMessage` | `string` | — | — | Custom validation message |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `input` | Fires on every keystroke |
+| `change` | Fires when value is committed |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `validate()` | Validate; sets `invalid` |
+| `reset()` | Reset value |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `field` | Outer wrapper |
+| `container` | Textarea area wrapper |
+| `textarea` | Native `<textarea>` element |
+| `counter` | Character counter display |

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

@@ -0,0 +1,58 @@
+# u-tooltip
+
+```ts
+import '@iyulab/components/dist/components/tooltip/UTooltip.js';
+```
+
+**Tag:** `u-tooltip`
+
+Hover/focus tooltip anchored to a `for` target. Opens and closes automatically.
+
+```html
+<u-button id="save-btn">Save</u-button>
+<u-tooltip for="#save-btn" placement="top">
+  Save your changes (Ctrl+S)
+</u-tooltip>
+
+<!-- Interactive tooltip (stays open when hovered) -->
+<u-tooltip for="#info" interactive placement="bottom" offset="8">
+  <a href="/docs">Learn more</a>
+</u-tooltip>
+
+<!-- Tracking cursor position -->
+<u-tooltip for="#chart" tracking>
+  Data point detail
+</u-tooltip>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip content |
+
+## Properties
+
+Inherits all `UFloatingElement` properties (see [floating.md](../extensions/floating.md)), plus:
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `for` | `string` | — | ✓ | CSS selector of the target element |
+| `open` | `boolean` | `false` | ✓ | Visibility state |
+| `placement` | `Placement` | — | — | Preferred placement |
+| `offset` | `OffsetOptions` | `0` | — | Gap from target |
+| `shift` | `boolean` | `false` | — | Auto-shift to stay in viewport |
+| `arrow` | `boolean` | `false` | — | Show pointing arrow |
+| `showDelay` | `number` | `0` | — | Open delay in ms |
+| `hideDelay` | `number` | `0` | — | Close delay in ms |
+| `interactive` | `boolean` | `false` | ✓ | Keep open when mouse is over tooltip |
+| `tracking` | `boolean` | `false` | ✓ | Follow mouse cursor position |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Before tooltip opens |
+| `hide` | ✓ | Before tooltip closes |

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 |