@iyulab/components 0.4.0 → 1.0.0

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

@@ -0,0 +1,74 @@
+# u-alert
+
+```ts
+import '@iyulab/components/dist/components/alert/UAlert.js';
+```
+
+**Tag:** `u-alert`
+
+Closable message banner with status icons, auto-dismiss timer, and open/hide transition.
+
+```html
+<u-alert status="success" closable open>
+  Your changes have been saved.
+</u-alert>
+
+<u-alert status="error" variant="outlined" open>
+  Failed to load data.
+  <u-button slot="footer" variant="solid">Retry</u-button>
+</u-alert>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Alert body content |
+| `footer` | Bottom area (e.g. action buttons) |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Show/hide the alert |
+| `closable` | `boolean` | `false` | ✓ | Show close button |
+| `variant` | `'solid'\|'filled'\|'outlined'\|'glass'` | `'solid'` | ✓ | Visual style |
+| `status` | `'error'\|'warning'\|'success'\|'info'\|'notice'` | — | ✓ | Status type; controls icon and color |
+| `title` | `string` | `''` | — | Title label (falls back to status name) |
+| `duration` | `number` | `0` | — | Auto-dismiss delay in ms; `0` disables |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Fires before the alert becomes visible |
+| `hide` | ✓ | Fires before the alert is hidden |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `boolean` | Opens the alert; returns `false` if cancelled |
+| `hide()` | `boolean` | Closes the alert; returns `false` if cancelled |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Outer flex column wrapper |
+| `header` | Row containing icon, title, and close button |
+| `icon` | Status icon (hidden when `status` is unset) |
+| `title` | Title text |
+| `close-btn` | Close button (visible when `closable`) |
+| `content` | Scrollable body area |
+| `footer` | Footer slot wrapper |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--alert-background-color` | Background color (auto-set by status) |
+| `--alert-border-color` | Border color (auto-set by status) |
+| `--alert-icon-color` | Icon color (auto-set by status) |

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

@@ -0,0 +1,41 @@
+# u-avatar
+
+```ts
+import '@iyulab/components/dist/components/avatar/UAvatar.js';
+```
+
+**Tag:** `u-avatar`
+
+Displays a user avatar as an image, initials label, or custom slot content.
+
+```html
+<u-avatar image="/photo.jpg" label="Alice"></u-avatar>
+<u-avatar label="AB" shape="square"></u-avatar>
+<u-avatar outline>
+  <u-icon lib="tabler" name="user"></u-icon>
+</u-avatar>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Custom content shown when neither `image` nor `label` is set |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `shape` | `'circle'\|'square'\|'rounded'` | `'circle'` | ✓ | Avatar shape |
+| `outline` | `boolean` | `false` | ✓ | Show border ring |
+| `image` | `string` | — | — | Image URL |
+| `label` | `string` | — | — | Initials text (first 2 chars shown; used as `alt` for image) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `image` | `<img>` element |
+| `label` | Initials `<span>` element |

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

@@ -0,0 +1,38 @@
+# u-badge
+
+```ts
+import '@iyulab/components/dist/components/badge/UBadge.js';
+```
+
+**Tag:** `u-badge`
+
+Status badge for numbers, labels, or dot indicators. Use `anchor` to position it absolutely on a parent element.
+
+```html
+<!-- Standalone -->
+<u-badge color="red">5</u-badge>
+
+<!-- Anchored on another element -->
+<div style="position:relative; display:inline-block;">
+  <u-icon lib="tabler" name="bell"></u-icon>
+  <u-badge variant="dot" color="red" anchor="top-right"></u-badge>
+</div>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Content before the main label |
+| *(default)* | Badge label (text or icon) |
+| `suffix` | Content after the main label |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'pill'\|'dot'\|'square'` | `'pill'` | ✓ | Shape variant; `dot` renders no content |
+| `color` | `'neutral'\|'blue'\|'green'\|'yellow'\|'red'\|'orange'\|'teal'\|'cyan'\|'purple'\|'pink'` | `'neutral'` | ✓ | Badge color |
+| `anchor` | `'top-right'\|'top-left'\|'bottom-right'\|'bottom-left'` | — | ✓ | Absolute anchor position relative to parent |

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

@@ -0,0 +1,75 @@
+# u-breadcrumb / u-breadcrumb-item
+
+```ts
+import '@iyulab/components/dist/components/breadcrumb/UBreadcrumb.js';
+import '@iyulab/components/dist/components/breadcrumb-item/UBreadcrumbItem.js';
+```
+
+**Tags:** `u-breadcrumb`, `u-breadcrumb-item`
+
+Hierarchical location indicator. Compose `u-breadcrumb-item` elements inside `u-breadcrumb`.
+
+```html
+<u-breadcrumb>
+  <u-breadcrumb-item href="/">Home</u-breadcrumb-item>
+  <u-breadcrumb-item href="/products">Products</u-breadcrumb-item>
+  <u-breadcrumb-item>Detail</u-breadcrumb-item>
+</u-breadcrumb>
+
+<!-- Custom separator -->
+<u-breadcrumb>
+  <span slot="separator">/</span>
+  <u-breadcrumb-item href="/">Home</u-breadcrumb-item>
+  <u-breadcrumb-item>Page</u-breadcrumb-item>
+</u-breadcrumb>
+```
+
+---
+
+## u-breadcrumb
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-breadcrumb-item` elements |
+| `separator` | Custom separator content (default: chevron icon) |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `nav` | `<nav>` wrapper element |
+
+---
+
+## u-breadcrumb-item
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Content before the label |
+| *(default)* | Item label |
+| `suffix` | Content after the label |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `disabled` | `boolean` | `false` | ✓ | Disable the item |
+| `href` | `string` | — | — | Link URL; renders as `<a>` when set |
+| `target` | `string` | — | — | Link `target` attribute |
+| `rel` | `string` | — | — | Link `rel` attribute |
+
+### Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `navigate` | ✓ | Fires when the item is clicked |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `link` | Inner `<a>` or `<span>` element |

package/skills/iyulab-components/references/components/button-group.md

@@ -0,0 +1,38 @@
+# u-button-group
+
+```ts
+import '@iyulab/components/dist/components/button-group/UButtonGroup.js';
+```
+
+**Tag:** `u-button-group`
+
+Groups `u-button` or `u-icon-button` elements. Propagates `variant` and `disabled` to all child buttons automatically.
+
+```html
+<u-button-group variant="outlined">
+  <u-button>Left</u-button>
+  <u-button>Center</u-button>
+  <u-button>Right</u-button>
+</u-button-group>
+
+<u-button-group vertical disabled>
+  <u-button>Top</u-button>
+  <u-button>Bottom</u-button>
+</u-button-group>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-button` or `u-icon-button` elements |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'\|'ghost'\|'link'` | `'solid'` | ✓ | Variant propagated to all child buttons |
+| `vertical` | `boolean` | `false` | ✓ | Stack buttons vertically |
+| `disabled` | `boolean` | `false` | ✓ | Disable all child buttons |

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

@@ -0,0 +1,56 @@
+# u-button
+
+```ts
+import '@iyulab/components/dist/components/button/UButton.js';
+```
+
+**Tag:** `u-button`
+
+Versatile button with multiple visual variants. Renders as an `<a>` element when `href` is provided.
+
+```html
+<u-button>Default</u-button>
+<u-button variant="outlined">Outlined</u-button>
+<u-button variant="ghost" loading>Loading</u-button>
+<u-button href="https://example.com" target="_blank">Link</u-button>
+
+<!-- With prefix/suffix icons -->
+<u-button variant="solid">
+  <u-icon slot="prefix" lib="tabler" name="download"></u-icon>
+  Download
+</u-button>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Button label |
+| `prefix` | Content before the label |
+| `suffix` | Content after the label |
+| `spinner` | Custom spinner shown when `loading` |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'\|'ghost'\|'link'` | `'solid'` | ✓ | Visual style |
+| `rounded` | `boolean` | `false` | ✓ | Pill-shaped border radius |
+| `disabled` | `boolean` | `false` | ✓ | Disable the button |
+| `loading` | `boolean` | `false` | ✓ | Show loading spinner; disables interaction |
+| `type` | `'button'\|'submit'\|'reset'` | `'button'` | — | Button `type` attribute |
+| `href` | `string` | — | — | Link URL (renders as `<a>`) |
+| `target` | `string` | — | — | Link `target` |
+| `rel` | `string` | — | — | Link `rel` |
+| `download` | `string` | — | — | Download filename |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `button` | Inner `<button>` element |
+| `link` | Inner `<a>` element (when `href` is set) |
+| `content` | Content wrapper (prefix + label + suffix) |
+| `mask` | Loading overlay mask |

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

@@ -0,0 +1,53 @@
+# u-card
+
+```ts
+import '@iyulab/components/dist/components/card/UCard.js';
+```
+
+**Tag:** `u-card`
+
+Content card with optional media, header, body, and footer sections.
+
+```html
+<u-card>
+  <img slot="media" src="/cover.jpg" alt="Cover" />
+  <span slot="header">Title</span>
+  <p>Card body content.</p>
+  <u-button slot="footer" variant="ghost">Read more</u-button>
+</u-card>
+
+<u-card orientation="horizontal" hoverable>
+  <img slot="media" src="/thumb.jpg" />
+  <p>Horizontal layout card.</p>
+</u-card>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `media` | Visual media (image, video) |
+| `header` | Card header area |
+| *(default)* | Card body content |
+| `footer` | Card footer area |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `orientation` | `'vertical'\|'horizontal'` | `'vertical'` | ✓ | Layout direction |
+| `shadowless` | `boolean` | `false` | ✓ | Remove drop shadow |
+| `borderless` | `boolean` | `false` | ✓ | Remove border |
+| `hoverable` | `boolean` | `false` | ✓ | Lift effect on hover |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `media` | Media area wrapper |
+| `content` | Full content wrapper (header + body + footer) |
+| `header` | Header slot wrapper |
+| `body` | Body (default slot) wrapper |
+| `footer` | Footer slot wrapper |

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

@@ -0,0 +1,63 @@
+# u-carousel
+
+```ts
+import '@iyulab/components/dist/components/carousel/UCarousel.js';
+```
+
+**Tag:** `u-carousel`
+
+Slide carousel. Each direct child element becomes one slide.
+
+```html
+<u-carousel navigation pagination loop autoplay>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</u-carousel>
+
+<!-- Multi-slide view -->
+<u-carousel slides-per-view="3" gap="16" draggable>
+  <div>A</div><div>B</div><div>C</div><div>D</div>
+</u-carousel>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Slide elements (each direct child = one slide) |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `autoplay` | `boolean` | `false` | Auto-advance slides |
+| `autoplayInterval` | `number` | `3000` | Auto-advance interval in ms |
+| `loop` | `boolean` | `false` | Loop from last to first |
+| `navigation` | `boolean` | `false` | Show prev/next buttons |
+| `pagination` | `boolean` | `false` | Show dot pagination |
+| `draggable` | `boolean` | `false` | Drag to navigate |
+| `slidesPerView` | `number` | `1` | Visible slides at once |
+| `slidesPerMove` | `number` | `1` | Slides to advance per step |
+| `gap` | `number` | `0` | Gap between slides in px |
+| `index` | `number` | `0` | Active slide index |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `prev()` | Go to previous slide |
+| `next()` | Go to next slide |
+| `goTo(index)` | Jump to a specific slide index |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `slides` | Slides track container |
+| `prev-button` | Previous navigation button |
+| `next-button` | Next navigation button |
+| `indicator` | Pagination indicator wrapper |
+| `dot` | Individual pagination dot |

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

@@ -0,0 +1,70 @@
+# u-checkbox
+
+```ts
+import '@iyulab/components/dist/components/checkbox/UCheckbox.js';
+```
+
+**Tag:** `u-checkbox`
+
+Checkbox with `indeterminate` state support. Form-associated (`formAssociated = true`).
+
+```html
+<u-checkbox name="agree" required>I agree to the terms</u-checkbox>
+
+<u-checkbox checked color="green" variant="outline">
+  Enabled feature
+</u-checkbox>
+
+<!-- Indeterminate (partial selection) -->
+<u-checkbox indeterminate>Select all</u-checkbox>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Label text |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `checked` | `boolean` | `false` | ✓ | Checked state |
+| `indeterminate` | `boolean` | `false` | ✓ | Partial / indeterminate state |
+| `variant` | `'filled'\|'outline'` | `'filled'` | ✓ | Visual style |
+| `color` | `'blue'\|'green'\|'red'\|'orange'\|'teal'\|'cyan'\|'purple'\|'pink'\|'neutral'` | `'blue'` | ✓ | Accent color |
+| `disabled` | `boolean` | `false` | ✓ | Disable the control |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required field |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed state |
+| `name` | `string` | — | — | Form field name |
+| `value` | `string` | — | — | Submitted value |
+| `label` | `string` | — | — | Label (alternative to slot) |
+| `validationMessage` | `string` | — | — | Custom validation message |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `validate()` | `boolean` | Run validation; sets `invalid` |
+| `reset()` | `void` | Clear value and validation state |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `wrapper` | Outer layout wrapper |
+| `input` | Hidden native `<input>` |
+| `checkbox` | Visual checkbox box |
+| `label` | Label text element |
+| `description` | Description text |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--checkbox-color` | Checkmark color |
+| `--checkbox-border-color` | Border color |
+| `--checkbox-background-color` | Fill color when checked |

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

@@ -0,0 +1,64 @@
+# u-chip
+
+```ts
+import '@iyulab/components/dist/components/chip/UChip.js';
+```
+
+**Tag:** `u-chip`
+
+Interactive chip tag. Supports selectable toggle, removable button, and tooltip.
+
+```html
+<u-chip>React</u-chip>
+
+<u-chip selectable color="blue">TypeScript</u-chip>
+
+<u-chip removable @remove=${() => console.log('removed')}>
+  Delete me
+</u-chip>
+
+<!-- Tooltip on hover -->
+<u-chip>
+  Tag
+  <span slot="tooltip">More details here</span>
+</u-chip>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Content before the label |
+| *(default)* | Chip label |
+| `suffix` | Content after the label |
+| `tooltip` | Tooltip content shown on hover |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'filled'\|'solid'\|'surface'\|'outlined'` | `'filled'` | ✓ | Visual style |
+| `color` | `'neutral'\|'blue'\|'green'\|'yellow'\|'red'\|'orange'\|'teal'\|'cyan'\|'purple'\|'pink'` | `'neutral'` | ✓ | Color |
+| `rounded` | `boolean` | `false` | ✓ | Pill-shaped |
+| `removable` | `boolean` | `false` | ✓ | Show remove button |
+| `selectable` | `boolean` | `false` | ✓ | Can be toggled selected |
+| `selected` | `boolean` | `false` | ✓ | Selected state |
+| `value` | `string` | `''` | — | Unique identifier value |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `pick` | Fires when the chip is selected/deselected |
+| `remove` | Fires when the remove button is clicked |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `tag` | Main chip wrapper |
+| `check` | Check icon shown when selected |
+| `remove` | Remove button |
+| `tooltip` | Tooltip element |

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

@@ -0,0 +1,71 @@
+# u-dialog
+
+```ts
+import '@iyulab/components/dist/components/dialog/UDialog.js';
+```
+
+**Tag:** `u-dialog`
+
+Modal or non-modal dialog window. Supports focus-trap, scroll-lock, ESC/backdrop close, and configurable placement.
+
+For programmatic usage (`Dialog.alert`, `Dialog.confirm`, `Dialog.prompt`), see [dialog.md](../utilities/dialog.md).
+
+```html
+<u-dialog id="dlg" closable placement="center">
+  <span slot="header">Confirm Action</span>
+  <p>Are you sure you want to delete this item?</p>
+  <div slot="footer">
+    <u-button variant="ghost" @click=${() => dlg.hide()}>Cancel</u-button>
+    <u-button variant="solid" @click=${handleConfirm}>Delete</u-button>
+  </div>
+</u-dialog>
+
+<u-button @click=${() => dlg.show()}>Open</u-button>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `header` | Dialog header area |
+| *(default)* | Dialog body content |
+| `footer` | Dialog footer area |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Show/hide state |
+| `closable` | `boolean` | `false` | ✓ | Show close button |
+| `placement` | `'top-start'\|'top'\|'top-end'\|'start'\|'center'\|'end'\|'bottom-start'\|'bottom'\|'bottom-end'` | `'center'` | ✓ | Position on screen |
+| `offset` | `number` | `0` | ✓ | Distance from screen edge in px |
+| `mode` | `'modal'\|'non-modal'` | `'modal'` | ✓ | `modal` enables focus-trap |
+| `contained` | `boolean` | `false` | ✓ | Position relative to parent element |
+| `closeOn` | `string[]` | `['escape','backdrop','button']` | ✓ | Close triggers |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Before the dialog opens |
+| `hide` | ✓ | Before the dialog closes |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `boolean` | Open the dialog |
+| `hide()` | `boolean` | Close the dialog |
+| `requestClose(source)` | `void` | Request close from a given source (checks `closeOn` policy) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Backdrop/positioning wrapper |
+| `panel` | The dialog panel |
+| `header` | Header area |
+| `body` | Body area |
+| `close-btn` | Close button |