@iyulab/components 0.3.0 → 1.0.0

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 |

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

@@ -0,0 +1,56 @@
+# u-divider
+
+```ts
+import '@iyulab/components/dist/components/divider/UDivider.js';
+```
+
+**Tag:** `u-divider`
+
+Horizontal or vertical separator line. Slot content is overlaid as an inline label.
+
+```html
+<u-divider></u-divider>
+
+<u-divider>OR</u-divider>
+
+<u-divider variant="dashed" align="start">Section</u-divider>
+
+<!-- Vertical -->
+<div style="display:flex; height:40px;">
+  <span>Left</span>
+  <u-divider vertical></u-divider>
+  <span>Right</span>
+</div>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Optional label overlaid on the divider line |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `vertical` | `boolean` | `false` | ✓ | Vertical orientation |
+| `variant` | `'solid'\|'dashed'\|'dotted'` | `'solid'` | ✓ | Line style |
+| `align` | `'start'\|'center'\|'end'` | `'center'` | ✓ | Label alignment |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `line-start` | Line segment before the label |
+| `label` | Label wrapper |
+| `line-end` | Line segment after the label |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--divider-size` | Line thickness |
+| `--divider-color` | Line color |
+| `--divider-spacing` | Spacing around the label |

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

@@ -0,0 +1,63 @@
+# u-drawer
+
+```ts
+import '@iyulab/components/dist/components/drawer/UDrawer.js';
+```
+
+**Tag:** `u-drawer`
+
+Side panel that slides in from any screen edge. Extends `UOverlayElement` (focus-trap, scroll-lock, close policy).
+
+```html
+<u-drawer id="drawer" placement="right" closable>
+  <span slot="header">Settings</span>
+  <p>Drawer content here.</p>
+  <u-button slot="footer" @click=${() => drawer.hide()}>Close</u-button>
+</u-drawer>
+
+<u-button @click=${() => drawer.show()}>Open Drawer</u-button>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `header` | Drawer header |
+| *(default)* | Drawer body content |
+| `footer` | Drawer footer |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Show/hide state |
+| `closable` | `boolean` | `false` | ✓ | Show close button |
+| `placement` | `'left'\|'right'\|'top'\|'bottom'` | `'left'` | ✓ | Slide-in direction |
+| `mode` | `'modal'\|'non-modal'` | `'modal'` | ✓ | Focus-trap mode |
+| `contained` | `boolean` | `false` | ✓ | Contained to parent element |
+| `closeOn` | `string[]` | `['escape','backdrop','button']` | ✓ | Close triggers |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Before drawer opens |
+| `hide` | ✓ | Before drawer closes |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `show()` | Open the drawer |
+| `hide()` | Close the drawer |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `panel` | Drawer panel |
+| `header` | Header area |
+| `body` | Body area |
+| `close-btn` | Close button |

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

@@ -0,0 +1,42 @@
+# u-field
+
+```ts
+import '@iyulab/components/dist/components/field/UField.js';
+```
+
+**Tag:** `u-field`
+
+Layout wrapper for form controls. Renders label, required marker, description text, and validation message around any control.
+
+```html
+<u-field label="Email" required description="We'll never share your email.">
+  <u-input type="email" name="email"></u-input>
+</u-field>
+
+<u-field label="Role" invalid validation-message="Please select a role.">
+  <u-select name="role">
+    <u-option value="admin">Admin</u-option>
+  </u-select>
+  <u-button slot="label-aside" variant="link">Learn more</u-button>
+</u-field>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | The form control to wrap |
+| `label-aside` | Content placed to the right of the label |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `label` | `string` | — | — | Label text |
+| `description` | `string` | — | — | Helper text shown below the control |
+| `validationMessage` | `string` | — | — | Error message shown when `invalid` |
+| `required` | `boolean` | `false` | ✓ | Show required marker |
+| `invalid` | `boolean` | `false` | ✓ | Show validation error state |
+| `disabled` | `boolean` | `false` | ✓ | Disable state forwarding |

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

@@ -0,0 +1,68 @@
+# u-form
+
+```ts
+import '@iyulab/components/dist/components/form/UForm.js';
+```
+
+**Tag:** `u-form`
+
+Form group with two-way model binding. Wraps `UFormControlElement`-based controls and observes value changes.
+
+```html
+<u-form id="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-form>
+```
+
+```ts
+const form = document.querySelector('#form') as UForm;
+
+// Set initial model values
+form.model = { email: 'user@example.com', role: 'viewer' };
+
+// Listen for changes
+form.addEventListener('change', () => {
+  console.log(form.model); // { email: '...', role: '...' }
+});
+
+// Validate all controls
+if (form.validate()) {
+  submitData(form.model);
+}
+
+// Reset all controls
+form.reset();
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Form control elements |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `model` | `Record<string, unknown>` | — | Two-way bound data model |
+| `includes` | `string[]` | `[]` | Only include these field names (empty = all) |
+| `excludes` | `string[]` | `[]` | Exclude these field names |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when any control value changes |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `validate()` | `boolean` | Validate all child controls |
+| `reset()` | `void` | Reset all child controls |

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

@@ -0,0 +1,56 @@
+# u-icon-button
+
+```ts
+import '@iyulab/components/dist/components/icon-button/UIconButton.js';
+```
+
+**Tag:** `u-icon-button`
+
+Square icon-only button with a built-in tooltip (shown from the default slot). Renders as `<a>` when `href` is set.
+
+```html
+<u-icon-button lib="tabler" name="trash">
+  Delete
+</u-icon-button>
+
+<u-icon-button variant="outlined" rounded lib="heroicons" name="plus:solid">
+  Add item
+</u-icon-button>
+
+<u-icon-button href="/settings" lib="tabler" name="settings">
+  Settings
+</u-icon-button>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip content (shown on hover) |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'\|'ghost'\|'link'` | `'ghost'` | ✓ | Button variant |
+| `rounded` | `boolean` | `false` | ✓ | Circular shape |
+| `disabled` | `boolean` | `false` | ✓ | Disable the button |
+| `loading` | `boolean` | `false` | ✓ | Loading state |
+| `href` | `string` | — | — | Link URL (renders as `<a>`) |
+| `target` | `string` | — | — | Link `target` |
+| `rel` | `string` | — | — | Link `rel` |
+| `lib` | `string` | — | — | Icon library |
+| `name` | `string` | — | — | Icon name |
+| `src` | `string` | — | — | Raw SVG source |
+| `tooltipPlacement` | `Placement` | `'top'` | — | Tooltip position |
+| `tooltipOffset` | `OffsetOptions` | `4` | — | Tooltip offset from button |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `button` | Inner `<button>` or `<a>` |
+| `icon` | `u-icon` element |
+| `tooltip` | Built-in `u-tooltip` element |

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

@@ -0,0 +1,49 @@
+# u-icon
+
+```ts
+import '@iyulab/components/dist/components/icon/UIcon.js';
+```
+
+**Tag:** `u-icon`
+
+Renders an SVG icon by name from a registered icon library. Inline `src` also accepted.
+
+```html
+<!-- Built-in -->
+<u-icon lib="internal" name="check-circle-fill"></u-icon>
+
+<!-- Tabler (CDN) -->
+<u-icon lib="tabler" name="home"></u-icon>
+<u-icon lib="tabler" name="home:filled"></u-icon>
+
+<!-- Heroicons -->
+<u-icon lib="heroicons" name="academic-cap:solid"></u-icon>
+
+<!-- Lucide -->
+<u-icon lib="lucide" name="activity"></u-icon>
+
+<!-- Bootstrap Icons -->
+<u-icon lib="bootstrap" name="alarm"></u-icon>
+<u-icon lib="bootstrap" name="alarm:filled"></u-icon>
+
+<!-- Inline SVG -->
+<u-icon src='<svg ...>...</svg>'></u-icon>
+```
+
+For registering custom libraries, see [icons.md](../utilities/icons.md).
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `lib` | `'internal'\|'tabler'\|'heroicons'\|'lucide'\|'bootstrap'\|string` | — | Icon library identifier |
+| `name` | `string` | — | Icon name (library-specific; append `:filled` / `:solid` for filled variants) |
+| `src` | `string` | — | Raw SVG string (overrides `lib`/`name`) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `svg` | The rendered `<svg>` element |