@vc-shell/framework 1.1.0-alpha.9 → 1.1.0

package/ui/components/atoms/vc-icon/README.md

@@ -0,0 +1,295 @@
+# VcIcon Component
+
+The `VcIcon` component is a versatile icon component that supports multiple icon libraries:
+
+- Font Awesome
+- Material Symbols
+- Bootstrap Icons
+- Lucide Icons
+- Custom SVG Components
+
+## Installation
+
+Before using specific icon types, make sure to install the corresponding libraries:
+
+### Font Awesome
+
+```bash
+npm install @fortawesome/fontawesome-free
+```
+
+Add to your main.js/ts:
+```js
+import '@fortawesome/fontawesome-free/css/all.css';
+```
+
+### Material Icons
+
+```bash
+npm install material-symbols
+```
+
+Add to your main.js/ts:
+```js
+import 'material-symbols';
+```
+
+### Bootstrap Icons
+
+```bash
+npm install bootstrap-icons
+```
+
+Add to your main.js/ts:
+```js
+import 'bootstrap-icons/font/bootstrap-icons.css';
+```
+
+### Lucide Icons
+
+```bash
+npm install lucide-vue-next
+```
+
+Register the icons you need:
+```js
+// For local component usage
+import { HomeIcon, UserIcon } from 'lucide-vue-next';
+
+// For global registration
+import { createApp } from 'vue';
+import { LucideVue } from 'lucide-vue-next';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(LucideVue, { 
+  componentPrefix: '' // optional - default is 'Lucide'
+});
+```
+
+## Basic Usage
+
+### New Unified Syntax (Recommended)
+
+Use a consistent naming approach with library prefix for all icon types:
+
+```vue
+<template>
+  <!-- Font Awesome Icon (unchanged, already has prefix) -->
+  <VcIcon icon="fas fa-home" />
+  
+  <!-- Material Icon with prefix -->
+  <VcIcon icon="material-home" />
+  
+  <!-- Bootstrap Icon (unchanged, already has prefix) -->
+  <VcIcon icon="bi-house" />
+  
+  <!-- Lucide Icon with prefix -->
+  <VcIcon icon="lucide-home" />
+  
+  <!-- Direct component usage (for tree-shaking) -->
+  <VcIcon :icon="HomeIcon" />
+</template>
+
+<script setup lang="ts">
+import { HomeIcon } from 'lucide-vue-next';
+import VcIcon from 'path/to/vc-icon.vue';
+</script>
+```
+
+### Legacy Syntax (Still Supported)
+
+```vue
+<template>
+  <!-- Font Awesome Icon -->
+  <VcIcon icon="fas fa-home" />
+  
+  <!-- Material Icon (no prefix needed) -->
+  <VcIcon icon="home" />
+  
+  <!-- Bootstrap Icon -->
+  <VcIcon icon="bi-house" />
+  
+  <!-- Lucide Icon with explicit type parameter -->
+  <VcIcon icon="HomeIcon" type="lucide" />
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `string \| Component` | `"fas fa-square-full"` | The icon to display. Can be a string identifier or a component instance |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"` | Size of the icon |
+| `variant` | `"warning" \| "danger" \| "success"` | `undefined` | Color variant |
+| `type` | `"fontawesome" \| "material" \| "bootstrap" \| "lucide" \| "custom" \| "auto"` | `"auto"` | Icon library type. Use `auto` for automatic detection (legacy) |
+| `materialIconType` | `"outlined" \| "rounded" \| "sharp"` | `"outlined"` | Type of Material icon |
+| `materialIconFill` | `number` | `0` | Fill property for Material icons |
+| `materialIconWeight` | `number` | `400` | Weight property for Material icons |
+| `materialIconGrade` | `number` | `0` | Grade property for Material icons |
+| `strokeWidth` | `number` | `2` | Stroke width for Lucide icons |
+
+## Auto Detection
+
+The component automatically detects the icon type based on the icon name:
+
+- **Prefixed approach (recommended):**
+  - `material-name` → Material icon 
+  - `lucide-name` → Lucide icon
+  - `bi-name` → Bootstrap icon
+  - `fa-name` or `fas fa-name` → Font Awesome icon
+
+- **Legacy approach (still supported):**
+  - Strings containing `fa-` are treated as Font Awesome icons
+  - Strings starting with `bi-` are treated as Bootstrap icons
+  - Strings ending with `Icon` are treated as Lucide icons
+  - Other strings without these patterns are treated as Material icons
+  - Component instances are treated as custom SVG components
+
+## Size Mapping
+
+The component maps the size prop to pixel values:
+
+- `xs`: 12px
+- `s`: 14px
+- `m`: 18px
+- `l`: 20px
+- `xl`: 22px
+- `xxl`: 30px
+- `xxxl`: 64px
+
+> **Note about icon sizing:** 
+> 
+> Different icon libraries have naturally different sizing characteristics:
+> - **Font Awesome** icons are used as the base sizes (reference standard)
+> - **Bootstrap Icons** require a slight reduction (factor 0.95)
+> - **Material Icons** require a slight increase (factor 1.1)
+> - **Lucide Icons** (SVG) require a significant increase (factor 1.2)
+>
+> The `VcIcon` component automatically applies the necessary adjustments for visual consistency across all icon types. Thanks to this, developers can specify the same size (`size="m"`) for all icons and achieve a visually consistent result.
+
+## Examples
+
+### Font Awesome
+
+```vue
+<VcIcon icon="fas fa-home" />
+<VcIcon icon="far fa-user" />
+<VcIcon icon="fas fa-cog" size="xl" />
+<VcIcon icon="fas fa-exclamation-triangle" variant="warning" />
+```
+
+### Material Icons
+
+```vue
+<!-- Legacy syntax -->
+<VcIcon icon="home" />
+<VcIcon icon="settings" materialIconType="rounded" />
+
+<!-- New syntax with prefix -->
+<VcIcon icon="material-home" />
+<VcIcon icon="material-settings" materialIconType="rounded" />
+<VcIcon icon="material-warning" variant="warning" size="xl" />
+```
+
+### Bootstrap Icons
+
+```vue
+<VcIcon icon="bi-house" />
+<VcIcon icon="bi-person" />
+<VcIcon icon="bi-gear" size="xl" />
+<VcIcon icon="bi-exclamation-triangle" variant="warning" />
+```
+
+### Lucide Icons
+
+```vue
+<template>
+  <!-- Legacy syntax with type parameter -->
+  <VcIcon icon="HomeIcon" type="lucide" />
+  
+  <!-- New syntax with prefix -->
+  <VcIcon icon="lucide-home" />
+  <VcIcon icon="lucide-settings" size="xl" />
+  <VcIcon icon="lucide-alert-triangle" variant="warning" />
+  
+  <!-- Direct component usage (preferred for tree-shaking) -->
+  <VcIcon :icon="HomeIcon" />
+</template>
+
+<script setup>
+import { HomeIcon, SettingsIcon, AlertTriangle } from 'lucide-vue-next';
+</script>
+```
+
+## Migration Guide
+
+### From Custom SVG Components to Material Icons
+
+```vue
+<!-- Before -->
+<VcIcon icon="SearchIcon" />
+<VcIcon icon="HomeIcon" />
+
+<!-- After (legacy) -->
+<VcIcon icon="search" />
+<VcIcon icon="home" />
+
+<!-- After (new syntax) -->
+<VcIcon icon="material-search" />
+<VcIcon icon="material-home" />
+```
+
+### From Font Awesome to Bootstrap Icons
+
+```vue
+<!-- Before -->
+<VcIcon icon="fas fa-home" />
+<VcIcon icon="fas fa-user" />
+<VcIcon icon="fas fa-cog" />
+
+<!-- After -->
+<VcIcon icon="bi-house" />
+<VcIcon icon="bi-person" />
+<VcIcon icon="bi-gear" />
+```
+
+### From Material Icons to Lucide Icons
+
+```vue
+<!-- Before -->
+<VcIcon icon="home" />
+<VcIcon icon="settings" />
+
+<!-- After (legacy) -->
+<VcIcon icon="HomeIcon" type="lucide" />
+<VcIcon icon="SettingsIcon" type="lucide" />
+
+<!-- After (new syntax) -->
+<VcIcon icon="lucide-home" />
+<VcIcon icon="lucide-settings" />
+
+<!-- Or with direct components (preferred for tree-shaking) -->
+<template>
+  <VcIcon :icon="HomeIcon" />
+  <VcIcon :icon="SettingsIcon" />
+</template>
+
+<script setup>
+import { HomeIcon, SettingsIcon } from 'lucide-vue-next';
+</script>
+```
+
+## Icon Picker Tool
+
+To help developers choose the right icon name from each library, we recommend using these resources:
+
+- **Font Awesome**: [https://fontawesome.com/icons](https://fontawesome.com/icons)
+- **Material Symbols**: [https://fonts.google.com/icons](https://fonts.google.com/icons)
+- **Bootstrap Icons**: [https://icons.getbootstrap.com/](https://icons.getbootstrap.com/)
+- **Lucide Icons**: [https://lucide.dev/icons/](https://lucide.dev/icons/)
+
+## Material Icon Documentation
+For a complete list of available Material icons, visit:
+- [Material Symbols Documentation](https://fonts.google.com/icons)
+- [Material Symbols Demo](https://marella.github.io/material-symbols/demo/) 

package/ui/components/atoms/vc-icon/icons/VendorSwitchIcon.vue

@@ -0,0 +1,26 @@
+
+<template>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none" :width="width" :height="height">
+  <g stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <!-- First profile -->
+    <circle cx="6" cy="6" r="3" fill="none" />
+    <path d="M2 14V13C2 11.3431 3.34315 10 5 10H7C8.65685 10 10 11.3431 10 13V14" />
+
+    <!-- Second profile -->
+    <circle cx="14" cy="6" r="3" fill="none" />
+    <path d="M10 14V13C10 11.3431 11.3431 10 13 10H15C16.6569 10 18 11.3431 18 13V14" />
+
+    <!-- Switch/exchange arrows -->
+    <path d="M7 17L4 15L7 13" />
+    <path d="M13 17L16 15L13 13" />
+    <path d="M4 15H16" />
+  </g>
+</svg>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  width?: number | string
+  height?: number | string
+}>()
+</script>

package/ui/components/atoms/vc-icon/vc-bootstrap-icon.vue

@@ -0,0 +1,28 @@
+<template>
+  <i :class="[iconClass, variant ? `vc-icon_${variant}` : '']"></i>
+</template>
+
+<script lang="ts" setup>
+import { computed } from "vue";
+
+export interface Props {
+  icon: string;
+  size?: "xs" | "s" | "m" | "l" | "xl" | "xxl" | "xxxl";
+  variant?: "warning" | "danger" | "success";
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: "m",
+});
+
+// Normalize icon name to ensure it has the bi- prefix
+const normalizedIcon = computed(() => {
+  if (!props.icon) return "bi-question";
+  return props.icon.startsWith("bi-") ? props.icon : `bi-${props.icon}`;
+});
+
+// Bootstrap Icons class
+const iconClass = computed(() => {
+  return [`vc-icon`, `vc-icon_${props.size}`, normalizedIcon.value];
+});
+</script>

package/ui/components/atoms/vc-icon/vc-fontawesome-icon.vue

@@ -0,0 +1,41 @@
+<template>
+  <i :class="iconClass"></i>
+</template>
+
+<script lang="ts" setup>
+import { computed } from "vue";
+import type { IconSize, IconVariant } from "./vc-icon.vue";
+
+export interface Props {
+  icon: string;
+  size?: IconSize;
+  variant?: IconVariant;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: "m",
+});
+
+// Normalize the icon name to ensure a correct prefix
+const normalizedIcon = computed(() => {
+  if (!props.icon) return "";
+
+  // Handle cases where the icon is specified as "fa-icon-name" without the full prefix
+  if (
+    props.icon.startsWith("fa-") &&
+    !props.icon.startsWith("fas ") &&
+    !props.icon.startsWith("far ") &&
+    !props.icon.startsWith("fab ") &&
+    !props.icon.startsWith("fal ") &&
+    !props.icon.startsWith("fad ")
+  ) {
+    return `fas ${props.icon}`;
+  }
+
+  return props.icon;
+});
+
+const iconClass = computed(() => {
+  return [`vc-icon`, `vc-icon_${props.size}`, normalizedIcon.value, props.variant ? `vc-icon_${props.variant}` : ""];
+});
+</script>

package/ui/components/atoms/vc-icon/vc-icon-examples.vue

@@ -0,0 +1,183 @@
+<template>
+  <div class="icon-examples">
+    <h2>Examples of Using Different Icon Libraries</h2>
+
+    <div class="icon-section">
+      <h3>Font Awesome Icons</h3>
+      <div class="icon-grid">
+        <div class="icon-item">
+          <VcIcon icon="fas fa-home" />
+          <span>fas fa-home</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="far fa-user" />
+          <span>far fa-user</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="fas fa-cog"
+            size="xl"
+          />
+          <span>fas fa-cog (xl)</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="fas fa-exclamation-triangle"
+            variant="warning"
+          />
+          <span>fas fa-exclamation-triangle (warning)</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="icon-section">
+      <h3>Material Icons</h3>
+      <div class="icon-grid">
+        <div class="icon-item">
+          <VcIcon icon="material-home" />
+          <span>material-home</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="material-person" />
+          <span>material-person</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="material-settings"
+            size="xl"
+          />
+          <span>material-settings (xl)</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="material-warning"
+            variant="warning"
+          />
+          <span>material-warning (warning)</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="icon-section">
+      <h3>Bootstrap Icons</h3>
+      <div class="icon-grid">
+        <div class="icon-item">
+          <VcIcon icon="bi-house" />
+          <span>bi-house</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="bi-person" />
+          <span>bi-person</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="bi-gear"
+            size="xl"
+          />
+          <span>bi-gear (xl)</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="bi-exclamation-triangle"
+            variant="warning"
+          />
+          <span>bi-exclamation-triangle (warning)</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="icon-section">
+      <h3>Lucide Icons</h3>
+      <div class="icon-grid">
+        <div class="icon-item">
+          <VcIcon
+            icon="HomeIcon"
+            type="lucide"
+          />
+          <span>HomeIcon (legacy format)</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="lucide-home" />
+          <span>lucide-home</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="lucide-settings"
+            size="xl"
+          />
+          <span>lucide-settings (xl)</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon
+            icon="lucide-alert-triangle"
+            variant="warning"
+          />
+          <span>lucide-alert-triangle (warning)</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="icon-section">
+      <h3>Mixed Usage</h3>
+      <div class="icon-grid">
+        <div class="icon-item">
+          <VcIcon icon="fas fa-home" />
+          <span>Font Awesome</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="material-settings" />
+          <span>Material</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="bi-gear" />
+          <span>Bootstrap</span>
+        </div>
+        <div class="icon-item">
+          <VcIcon icon="lucide-home" />
+          <span>Lucide</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import VcIcon from "./vc-icon.vue";
+</script>
+
+<style lang="scss" scoped>
+.icon-examples {
+  padding: 20px;
+  font-family: sans-serif;
+}
+
+.icon-section {
+  margin-bottom: 30px;
+
+  h3 {
+    margin-bottom: 15px;
+    color: #444;
+  }
+}
+
+.icon-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 20px;
+}
+
+.icon-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 15px;
+  border: 1px solid #eee;
+  border-radius: 6px;
+
+  span {
+    margin-top: 10px;
+    font-size: 14px;
+    color: #666;
+  }
+}
+</style>