snice 4.24.1 → 4.25.0

package/docs/components/button.md

@@ -36,7 +36,7 @@ import 'snice/components/button/snice-button';
 | `href` | `string` | `''` | URL to navigate to (uses window.location, not an anchor tag) |
 | `target` | `string` | `''` | Link target attribute |
 | `download` | `string` | `''` | Download attribute for file downloads |
-| `icon` | `string` | `''` | Icon (URL, image file, emoji, or font ligature) |
+| `icon` | `string` | `''` | Icon (URL, image file, emoji). Use slot for icon fonts. |
 | `iconPlacement` | `'start' \| 'end'` | `'start'` | Icon position relative to label |
 
 ## Slots
@@ -48,37 +48,67 @@ import 'snice/components/button/snice-button';
 
 ### Icon Slot Usage
 
-The `icon` slot allows you to use external CSS-based icon fonts (like Material Symbols, Font Awesome) inside the button's shadow DOM. This is necessary because external fonts cannot style content inside shadow DOM boundaries.
+Use the `icon` slot for icon fonts (Material Symbols, Font Awesome, etc.) or inline SVGs. The slot gives you full control over the icon element and its styling.
 
+#### Material Symbols
 ```html
-<!-- Material Symbols icon -->
+<!-- Load the font in your document head -->
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet" />
+
 <snice-button variant="primary">
   <span slot="icon" class="material-symbols-outlined">save</span>
-  Save Document
+  Save
+</snice-button>
+
+<!-- With fill/weight variations -->
+<snice-button>
+  <span slot="icon" class="material-symbols-outlined" style="font-variation-settings: 'FILL' 1">favorite</span>
+  Liked
 </snice-button>
 
-<!-- Font Awesome icon -->
+<!-- Rounded variant -->
+<snice-button>
+  <span slot="icon" class="material-symbols-rounded">home</span>
+  Home
+</snice-button>
+```
+
+#### Font Awesome
+```html
+<!-- Load Font Awesome in your document head -->
+<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css" rel="stylesheet" />
+
 <snice-button variant="danger">
   <i slot="icon" class="fa-solid fa-trash"></i>
   Delete
 </snice-button>
 
-<!-- SVG icon -->
+<snice-button>
+  <i slot="icon" class="fa-regular fa-heart"></i>
+  Like
+</snice-button>
+```
+
+#### Inline SVG
+```html
 <snice-button>
   <svg slot="icon" viewBox="0 0 24 24" width="20" height="20">
     <path d="M12 2L2 7l10 5 10-5-10-5z" fill="currentColor"/>
   </svg>
   Upload
 </snice-button>
+```
 
-<!-- Icon at end position -->
+#### Placement
+The `icon-placement` property works with both the slot and the `icon` property:
+```html
 <snice-button icon-placement="end">
   <span slot="icon" class="material-symbols-outlined">arrow_forward</span>
   Next
 </snice-button>
 ```
 
-> **Note**: When using the `icon` slot, the slotted content takes precedence over the `icon` property. The `iconPlacement` property still controls positioning.
+> **Note**: The `icon` slot takes precedence over the `icon` property when both are present.
 
 ## Events
 
@@ -191,40 +221,35 @@ button.click();
 
 ### Buttons with Icons
 
-The `icon` property supports multiple formats:
-- **URLs**: Image files (`/icons/save.svg`, `https://...`)
-- **Inline SVG**: `<svg viewBox="...">...</svg>`
-- **Inline HTML**: `<span class="material-symbols-rounded">save</span>`
-- **Emoji**: Direct emoji characters (`→`, `🔍`)
-- **Font ligatures**: Text for icon fonts like Material Symbols (`save`, `home`)
+For icon fonts (Material Symbols, Font Awesome, etc.), use the `icon` slot — see [Icon Slot Usage](#icon-slot-usage) above.
 
-```html
-<!-- Icon URL -->
-<snice-button icon="/icons/arrow-right.svg">Next</snice-button>
+The `icon` **property** is for simple cases: emoji, image URLs, and image files.
 
-<!-- Emoji icon -->
+> **⚠️ `icon="home"` renders as plain text, not a Material icon.** Use the `icon` slot for icon fonts.
+
+```html
+<!-- Emoji -->
 <snice-button icon="→">Next</snice-button>
+<snice-button icon="🏠">Home</snice-button>
+<snice-button icon="💾" variant="primary">Save</snice-button>
 
-<!-- Font ligature (Material Symbols) -->
-<snice-button icon="arrow_forward">Next</snice-button>
+<!-- Image URL -->
+<snice-button icon="/icons/arrow-right.svg">Next</snice-button>
+<snice-button icon="https://example.com/icon.png">External</snice-button>
 
-<!-- Inline SVG -->
-<snice-button icon="<svg viewBox='0 0 24 24'><path d='M12 2L2 7l10 5 10-5-10-5z'/></svg>">
-  Upload
-</snice-button>
+<!-- Image file (auto-detected by extension) -->
+<snice-button icon="logo.svg">Brand</snice-button>
 
-<!-- Icon at end -->
-<snice-button icon="/icons/external-link.svg" icon-placement="end">
-  Open Link
-</snice-button>
+<!-- Icon placement -->
+<snice-button icon="→" icon-placement="end">Next</snice-button>
 
-<!-- Icon only (circle button) -->
+<!-- Icon-only circle button -->
 <snice-button circle icon="⚙️"></snice-button>
-<snice-button circle icon="settings"></snice-button>
+<snice-button circle icon="×"></snice-button>
 
-<!-- With variants -->
-<snice-button variant="primary" icon="💾">Save</snice-button>
-<snice-button variant="danger" icon="🗑️" outline>Delete</snice-button>
+<!-- Scheme overrides (force rendering mode) -->
+<snice-button icon="img://filename">Force as image</snice-button>
+<snice-button icon="text://content">Force as text</snice-button>
 ```
 
 ### Link Buttons

package/docs/components/chip.md

@@ -30,7 +30,7 @@ import 'snice/components/chip/snice-chip';
 | `removable` | `boolean` | `false` | Show remove button |
 | `selected` | `boolean` | `false` | Show selected state |
 | `disabled` | `boolean` | `false` | Disable the chip |
-| `icon` | `string` | `''` | Icon (URL, image file, emoji, or font ligature) |
+| `icon` | `string` | `''` | Icon (URL, image file, emoji). Use slot for icon fonts. |
 | `avatar` | `string` | `''` | Avatar image URL |
 
 ## Slots
@@ -130,9 +130,10 @@ chip.addEventListener('chip-remove', () => {
 
 The `icon` property supports multiple formats:
 - **URLs**: Image files (`/icons/star.svg`)
-- **Inline SVG**: `<svg>...</svg>`
 - **Emoji**: `★`, `🏠`, `⚙️`
-- **Font ligatures**: Text for icon fonts like Material Symbols (`star`, `home`)
+- **Scheme overrides**: `img://filename` forces `<img>`, `text://content` forces text
+
+> **⚠️ Common mistake:** `icon="home"` or `icon="settings"` renders as **plain text**, not a Material icon. Snice does not bundle Material Symbols. Use the `icon` slot instead.
 
 ```html
 <!-- Emoji icons -->
@@ -143,9 +144,10 @@ The `icon` property supports multiple formats:
 <!-- Image URL -->
 <snice-chip label="Star" icon="/icons/star.svg" variant="warning"></snice-chip>
 
-<!-- Font ligature (Material Symbols) -->
-<snice-chip label="Home" icon="home" variant="primary"></snice-chip>
-<snice-chip label="Settings" icon="settings" variant="default"></snice-chip>
+<!-- Icon slot for Material Symbols -->
+<snice-chip label="Home" variant="primary">
+  <span slot="icon" class="material-symbols-outlined">home</span>
+</snice-chip>
 ```
 
 ### Chips with Avatars

package/docs/components/empty-state.md

@@ -19,7 +19,7 @@ The `<snice-empty-state>` component provides a consistent way to display empty o
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
-| `icon` | `string` | `'📭'` | Icon (URL, image file, emoji, or font ligature) |
+| `icon` | `string` | `'📭'` | Icon (URL, image file, emoji). Use slot for icon fonts. |
 | `title` | `string` | `'No data'` | Title text |
 | `description` | `string` | `''` | Description text |
 | `actionText` | `string` | `''` | Action button text |

package/docs/components/input.md

@@ -73,26 +73,40 @@ Set the `password` attribute along with `type="password"` to show a visibility t
 
 ### Icons
 
-Use the `prefix-icon` and `suffix-icon` attributes to add icons. Supports emoji, URLs, image files, and Material Symbols ligatures.
+For icon fonts (Material Symbols, Font Awesome, etc.), use the `prefix-icon` and `suffix-icon` **slots**. The `prefix-icon` and `suffix-icon` **attributes** are for emoji, URLs, and image files only.
 
-```html
-<snice-input prefix-icon="🔍" placeholder="Search"></snice-input>
-<snice-input suffix-icon="✉️" type="email" label="Email"></snice-input>
-<snice-input prefix-icon="/icons/search.svg" placeholder="Search"></snice-input>
-<snice-input prefix-icon="search" placeholder="Search"></snice-input>
-```
+> **⚠️ `prefix-icon="search"` renders as plain text, not a Material icon.** Use the slot for icon fonts.
 
-### Icon Slots
-
-Use the `prefix-icon` and `suffix-icon` slots for custom icon content like external icon fonts.
+#### Icon Slots (for icon fonts and SVGs)
 
 ```html
+<!-- Material Symbols -->
 <snice-input placeholder="Search">
   <span slot="prefix-icon" class="material-symbols-outlined">search</span>
 </snice-input>
+
 <snice-input placeholder="Email">
   <span slot="suffix-icon" class="material-symbols-outlined">mail</span>
 </snice-input>
+
+<!-- Font Awesome -->
+<snice-input placeholder="Search">
+  <i slot="prefix-icon" class="fa-solid fa-magnifying-glass"></i>
+</snice-input>
+
+<!-- Both prefix and suffix -->
+<snice-input placeholder="Search users">
+  <span slot="prefix-icon" class="material-symbols-outlined">search</span>
+  <span slot="suffix-icon" class="material-symbols-outlined">person</span>
+</snice-input>
+```
+
+#### Icon Attributes (for emoji and image URLs)
+
+```html
+<snice-input prefix-icon="🔍" placeholder="Search"></snice-input>
+<snice-input suffix-icon="✉️" type="email" label="Email"></snice-input>
+<snice-input prefix-icon="/icons/search.svg" placeholder="Search"></snice-input>
 ```
 
 ### Clearable

package/docs/components/location.md

@@ -181,7 +181,7 @@ location.addEventListener('location-click', (e) => {
 | `longitude` | `number \| string` | `''` | Longitude coordinate |
 | `showMap` (attr: `show-map`) | `boolean` | `false` | Show embedded map |
 | `showIcon` (attr: `show-icon`) | `boolean` | `true` | Show location icon |
-| `icon` | `string` | `'📍'` | Icon (emoji, URL, or font ligature) |
+| `icon` | `string` | `'📍'` | Icon (emoji, URL). Use slot for icon fonts. |
 | `iconImage` (attr: `icon-image`) | `string` | `''` | Icon image URL |
 | `mapUrl` (attr: `map-url`) | `string` | `''` | Custom map URL |
 | `clickable` | `boolean` | `false` | Make location clickable |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "snice",
-  "version": "4.24.1",
+  "version": "4.25.0",
   "type": "module",
-  "description": "Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.",
+  "description": "A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
   "browser": "dist/index.iife.js",