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

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

@@ -0,0 +1,226 @@
+<template>
+  <div class="icon-test">
+    <h2>Icon Size Consistency Test</h2>
+    <p>All icons should appear visually the same size when using the same size value</p>
+
+
+
+    <div
+      v-for="size in sizes"
+      :key="size"
+      class="size-row"
+    >
+      <div class="size-label">Size: {{ size }}</div>
+      <div class="icon-row">
+        <div class="icon-box">
+          <VcIcon
+            icon="fas fa-home"
+            :size="size"
+            :use-container="useContainer"
+          />
+          <span>Font Awesome</span>
+        </div>
+        <div class="icon-box">
+          <VcIcon
+            icon="material-home"
+            :size="size"
+            :use-container="useContainer"
+          />
+          <span>Material</span>
+        </div>
+        <div class="icon-box">
+          <VcIcon
+            icon="bi-house"
+            :size="size"
+            :use-container="useContainer"
+          />
+          <span>Bootstrap</span>
+        </div>
+        <div class="icon-box">
+          <VcIcon
+            icon="lucide-home"
+            :size="size"
+            :use-container="useContainer"
+          />
+          <span>Lucide</span>
+        </div>
+      </div>
+
+      <div class="size-label">For comparison: square with size {{ sizeValues[size] }}</div>
+      <div
+        class="reference-container"
+        :class="`reference-${size}`"
+      ></div>
+    </div>
+
+    <div class="recommendation">
+      <h3>Recommendations</h3>
+      <p>
+        To ensure uniform icon sizes, the following approaches are used:
+        <ol>
+          <li>Unified size system for all icon types</li>
+          <li>Optical adjustments to compensate for each library's design characteristics</li>
+          <li>Containers slightly larger than the icon size for better visual appearance</li>
+        </ol>
+      </p>
+      <p>
+        Current optical adjustment settings:
+        <pre>
+:deep(.vc-icon) {
+  /* Optical adjustments for different icon libraries */
+  --material-icons-scale: {{ opticalCorrections.material }}; /* Material icons need to be larger */
+  --fontawesome-icons-scale: {{ opticalCorrections.fontawesome }}; /* FontAwesome icons need to be smaller */
+  --bootstrap-icons-scale: {{ opticalCorrections.bootstrap }}; /* Bootstrap icons are our baseline */
+  --lucide-icons-scale: {{ opticalCorrections.lucide }}; /* Lucide icons match bootstrap */
+}
+        </pre>
+      </p>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref, onMounted } from "vue";
+import VcIcon from "./vc-icon.vue";
+import type { IconSize } from "./vc-icon.vue";
+
+const sizes: IconSize[] = ["xs", "s", "m", "l", "xl", "xxl", "xxxl"];
+const useContainer = ref(true);
+
+// Size values for display
+const sizeValues = {
+  xs: "12px",
+  s: "14px",
+  m: "18px",
+  l: "20px",
+  xl: "22px",
+  xxl: "30px",
+  xxxl: "64px"
+};
+
+// Optical adjustments for different icon types
+const opticalCorrections = ref({
+  material: 1.2,
+  bootstrap: 1.0,
+  lucide: 1.0,
+  fontawesome: 0.9
+});
+
+// Get current values from CSS on load
+onMounted(() => {
+  const style = getComputedStyle(document.documentElement);
+
+  const materialCorrection = style.getPropertyValue('--material-icons-scale').trim();
+  const bootstrapCorrection = style.getPropertyValue('--bootstrap-icons-scale').trim();
+  const lucideCorrection = style.getPropertyValue('--lucide-icons-scale').trim();
+  const fontawesomeCorrection = style.getPropertyValue('--fontawesome-icons-scale').trim();
+
+  if (materialCorrection) opticalCorrections.value.material = parseFloat(materialCorrection);
+  if (bootstrapCorrection) opticalCorrections.value.bootstrap = parseFloat(bootstrapCorrection);
+  if (lucideCorrection) opticalCorrections.value.lucide = parseFloat(lucideCorrection);
+  if (fontawesomeCorrection) opticalCorrections.value.fontawesome = parseFloat(fontawesomeCorrection);
+});
+</script>
+
+<style lang="scss" scoped>
+.icon-test {
+  padding: 20px;
+  font-family: sans-serif;
+
+  h2, h3 {
+    margin-bottom: 16px;
+  }
+
+
+
+  .size-row {
+    margin-bottom: 40px;
+    border: 1px solid #eee;
+    padding: 20px;
+    border-radius: 8px;
+  }
+
+  .size-label {
+    font-size: 16px;
+    font-weight: bold;
+    margin-bottom: 16px;
+    margin-top: 20px;
+  }
+
+  .icon-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-around;
+    margin-bottom: 30px;
+
+    .icon-box {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+
+      span {
+        margin-top: 10px;
+        font-size: 12px;
+      }
+    }
+  }
+
+  .reference-container {
+    border: 1px dashed #ccc;
+    background-color: rgba(200, 200, 200, 0.2);
+
+    &.reference-xs { width: 12px; height: 12px; }
+    &.reference-s { width: 14px; height: 14px; }
+    &.reference-m { width: 18px; height: 18px; }
+    &.reference-l { width: 20px; height: 20px; }
+    &.reference-xl { width: 22px; height: 22px; }
+    &.reference-xxl { width: 30px; height: 30px; }
+    &.reference-xxxl { width: 64px; height: 64px; }
+  }
+
+  .recommendation {
+    margin-top: 30px;
+    padding: 20px;
+    background-color: #f8f9fa;
+    border-radius: 8px;
+
+    h3 {
+      margin-top: 0;
+      margin-bottom: 16px;
+    }
+
+    p {
+      margin-bottom: 16px;
+
+      &:last-child {
+        margin-bottom: 0;
+      }
+    }
+
+    ol {
+      padding-left: 20px;
+      margin: 10px 0;
+
+      li {
+        margin-bottom: 10px;
+      }
+    }
+
+    code {
+      background-color: #eee;
+      padding: 2px 4px;
+      border-radius: 4px;
+      font-family: monospace;
+    }
+
+    pre {
+      background-color: #f1f1f1;
+      padding: 10px;
+      border-radius: 4px;
+      overflow: auto;
+      font-family: monospace;
+      font-size: 13px;
+    }
+  }
+}
+</style>

package/ui/components/atoms/vc-icon/vc-icon.stories.ts

@@ -1,65 +1,393 @@
-import type { Meta, StoryFn } from "@storybook/vue3";
-import { VcIcon } from "./";
+import type { Meta, StoryObj } from "@storybook/vue3";
+import { VcIcon } from ".";
+import { SearchIcon, ChevronRightIcon, PlusSignIcon } from "./icons";
+import VcIconTest from "./vc-icon-test.vue";
+import VcIconExamples from "./vc-icon-examples.vue";
 
-const SIZE = ["xs", "s", "m", "l", "xl", "xxl", "xxxl"];
-const VARIANT = ["warning", "danger", "success"];
-
-export default {
-  title: "atoms/VcIcon",
+/**
+ * `VcIcon` is a versatile icon component that supports multiple icon types:
+ * - Font Awesome icons
+ * - Custom SVG components
+ * - Material Design icons
+ * - Bootstrap icons
+ * - Lucide icons
+ *
+ * It handles different sizing, color variants, and customization options for each icon library.
+ */
+const meta = {
+  title: "Atoms/VcIcon",
   component: VcIcon,
-  args: {
-    icon: "fas fa-star",
-    size: "m",
-  },
+  tags: ["autodocs"],
   argTypes: {
-    icon: { control: "text" },
+    icon: {
+      control: "text",
+      description:
+        "Icon to display. Can be a Font Awesome icon (e.g., 'fas fa-home'), Bootstrap icon (e.g., 'bi-house'), Material icon (e.g., 'material-home'), Lucide icon (e.g., 'lucide-home') or custom component",
+      table: {
+        type: { summary: "string | Component" },
+        defaultValue: { summary: "'fas fa-square-full'" },
+      },
+    },
     size: {
-      control: "radio",
-      options: SIZE,
+      control: { type: "select" },
+      options: ["xs", "s", "m", "l", "xl", "xxl", "xxxl"],
+      description: "Size of the icon",
       table: {
-        type: {
-          summary: SIZE.join(" | "),
-        },
+        type: { summary: "'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl' | 'xxxl'" },
+        defaultValue: { summary: "'m'" },
+        category: "Appearance",
       },
     },
     variant: {
-      control: "radio",
-      options: VARIANT,
+      control: { type: "select" },
+      options: [undefined, "warning", "danger", "success"],
+      description: "Color variant of the icon",
       table: {
-        type: {
-          summary: VARIANT.join(" | "),
-        },
+        type: { summary: "'warning' | 'danger' | 'success'" },
+        defaultValue: { summary: "undefined" },
+        category: "Appearance",
+      },
+    },
+    useContainer: {
+      control: { type: "boolean" },
+      description: "Whether to wrap the icon in a container for consistent spacing",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "true" },
+        category: "Layout",
+      },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The VcIcon component is designed to handle various icon types with a unified interface:
+
+- **Font Awesome icons**: Use class names like "fas fa-home"
+- **Bootstrap icons**: Use class names like "bi-house"
+- **Material Design icons**: Use prefixed names like "material-home"
+- **Lucide icons**: Use prefixed names like "lucide-home" or direct component imports
+- **Custom SVG components**: Pass components directly or reference by name
+
+The component automatically detects the icon type and renders it accordingly.
+        `,
       },
     },
   },
 } satisfies Meta<typeof VcIcon>;
 
-export const Primary: StoryFn<typeof VcIcon> = (args) => ({
-  components: { VcIcon },
-  setup() {
-    return { args };
-  },
-  template: '<vc-icon v-bind="args"></vc-icon>',
-});
-
-export const AllStates: StoryFn<typeof VcIcon> = (args) => ({
-  components: {
-    VcIcon,
-  },
-  setup() {
-    return { args, variants: VARIANT, sizes: SIZE };
-  },
-  template: `
-    <div>
-      <div v-for="variant in variants" :key="variant">
-        <h2 class="tw-font-bold">Color: {{variant}}</h2>
-        <div class="tw-space-x-4 tw-flex tw-flex-row">
-          <div v-for="size in sizes" :key="size" >
-            <h3 class="">Size: <span class="tw-font-bold">{{size}}</span></h3>
-            <vc-icon v-bind="{...args, variant, size}"></vc-icon>
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Basic example of using Font Awesome icons.
+ * These icons require the Font Awesome library to be loaded in your project.
+ */
+export const FontAwesome: Story = {
+  args: {
+    icon: "fas fa-shopping-cart",
+    size: "l",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Font Awesome icons are rendered as `<i>` elements with the provided class names. This shopping cart icon is commonly used in e-commerce applications.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of using a custom SVG component directly passed as a prop.
+ */
+export const CustomSvgIcon: Story = {
+  args: {
+    icon: SearchIcon,
+    size: "l",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Custom SVG components can be imported and passed directly to the `icon` prop. Search functionality is essential for product discovery in e-commerce.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of using Material Design icon with outlined style.
+ */
+export const MaterialOutlined: Story = {
+  args: {
+    icon: "material-shopping_bag",
+    size: "l",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Material Design icons with 'outlined' style have hollow interiors. The shopping bag icon is commonly used for orders and purchases in e-commerce applications.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of Bootstrap Icon usage.
+ */
+export const BootstrapIcon: Story = {
+  args: {
+    icon: "bi-cart",
+    size: "l",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Bootstrap icons can be used with the 'bi-' prefix. The cart icon is universal in e-commerce interfaces.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of Lucide Icon usage.
+ */
+export const LucideIcon: Story = {
+  args: {
+    icon: "lucide-shopping-bag",
+    size: "l",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Lucide icons can be used with the 'lucide-' prefix. These modern icons work well in clean e-commerce designs.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of an icon with the success variant.
+ */
+export const VariantSuccess: Story = {
+  args: {
+    icon: "material-check_circle",
+    size: "l",
+    variant: "success",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The success variant applies a success/confirmation color to the icon. Useful for confirming completed orders or successful payments.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of an icon with the warning variant.
+ */
+export const VariantWarning: Story = {
+  args: {
+    icon: "material-error_outline",
+    size: "l",
+    variant: "warning",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The warning variant applies a warning color to the icon. Use for indicating low stock or potential issues with orders.",
+      },
+    },
+  },
+};
+
+/**
+ * Example of an icon with the danger variant.
+ */
+export const VariantDanger: Story = {
+  args: {
+    icon: "material-highlight_off",
+    size: "l",
+    variant: "danger",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The danger variant applies an error/danger color to the icon. Useful for error states or cancellation actions in the checkout process.",
+      },
+    },
+  },
+};
+
+/**
+ * Example showing all sizes of the same icon.
+ */
+export const AllSizes: Story = {
+  render: (args) => ({
+    components: { VcIcon },
+    setup() {
+      const sizes = ["xs", "s", "m", "l", "xl", "xxl", "xxxl"];
+      return { sizes, args };
+    },
+    template: `
+      <div class="tw-flex tw-flex-col tw-gap-4">
+        <h3 class="tw-text-lg tw-font-medium">Available Sizes</h3>
+        <div class="tw-flex tw-items-end tw-gap-6">
+          <div v-for="size in sizes" :key="size" class="tw-flex tw-flex-col tw-items-center tw-gap-2">
+            <VcIcon :icon="args.icon || 'material-shopping_cart'" :size="size" />
+            <span class="tw-text-xs">{{size}}</span>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Comparison of all available icon sizes from xs to xxxl. Choose the appropriate size based on where the icon appears in your interface.",
+      },
+    },
+  },
+};
+
+/**
+ * Example showing all variants of the same icon.
+ */
+export const AllVariants: Story = {
+  render: (args) => ({
+    components: { VcIcon },
+    setup() {
+      const variants = [undefined, "warning", "danger", "success"];
+      return { variants, args };
+    },
+    template: `
+      <div class="tw-flex tw-flex-col tw-gap-4">
+        <h3 class="tw-text-lg tw-font-medium">Available Variants</h3>
+        <div class="tw-flex tw-gap-6">
+          <div v-for="(variant, index) in variants" :key="index" class="tw-flex tw-flex-col tw-items-center tw-gap-2">
+            <VcIcon :icon="args.icon || 'material-local_shipping'" :variant="variant" size="l" />
+            <span class="tw-text-xs">{{variant || 'default'}}</span>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Comparison of all available color variants: default, warning, danger, and success. The shipping icon demonstrates how status variations can indicate different delivery states.",
+      },
+    },
+  },
+};
+
+/**
+ * Common e-commerce icons used throughout interfaces.
+ */
+export const EcommerceIcons: Story = {
+  render: (args) => ({
+    components: { VcIcon },
+    setup() {
+      const ecommerceIcons = [
+        { icon: "material-shopping_cart", label: "Cart" },
+        { icon: "material-account_circle", label: "Account" },
+        { icon: "material-favorite", label: "Wishlist" },
+        { icon: "material-local_shipping", label: "Shipping" },
+        { icon: "material-inventory", label: "Products" },
+        { icon: "material-search", label: "Search" },
+        { icon: "material-payments", label: "Payment" },
+        { icon: "material-receipt_long", label: "Orders" },
+      ];
+      return { icons: ecommerceIcons, args };
+    },
+    template: `
+      <div class="tw-flex tw-flex-col tw-gap-4">
+        <h3 class="tw-text-lg tw-font-medium">Common E-commerce Icons</h3>
+        <div class="tw-grid tw-grid-cols-4 tw-gap-4">
+          <div v-for="item in icons" :key="item.icon" class="tw-flex tw-flex-col tw-items-center tw-gap-2 tw-p-4 tw-border tw-border-gray-200 tw-rounded">
+            <VcIcon :icon="item.icon" size="xl" />
+            <span class="tw-text-sm">{{item.label}}</span>
           </div>
         </div>
       </div>
-    </div>
-  `,
-});
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A collection of commonly used icons in e-commerce interfaces. These represent core functionality like cart, account, wishlist, shipping, products, search, payment, and orders.",
+      },
+    },
+  },
+};
+
+/**
+ * Interactive state icons used to indicate product or order status.
+ */
+export const StatusIcons: Story = {
+  render: (args) => ({
+    components: { VcIcon },
+    setup() {
+      const statusIcons = [
+        { icon: "material-check_circle", variant: "success", label: "In Stock" },
+        { icon: "material-error_outline", variant: "warning", label: "Low Stock" },
+        { icon: "material-highlight_off", variant: "danger", label: "Out of Stock" },
+        { icon: "material-local_shipping", variant: "success", label: "Shipped" },
+        { icon: "material-access_time", variant: "warning", label: "Processing" },
+        { icon: "material-inventory_2", variant: undefined, label: "New Arrival" },
+        { icon: "material-verified", variant: "success", label: "Verified" },
+        { icon: "material-percent", variant: undefined, label: "On Sale" },
+      ];
+      return { icons: statusIcons, args };
+    },
+    template: `
+      <div class="tw-flex tw-flex-col tw-gap-4">
+        <h3 class="tw-text-lg tw-font-medium">Product & Order Status Icons</h3>
+        <div class="tw-grid tw-grid-cols-4 tw-gap-4">
+          <div v-for="item in icons" :key="item.icon" class="tw-flex tw-items-center tw-gap-2 tw-p-4 tw-border tw-border-gray-200 tw-rounded">
+            <VcIcon :icon="item.icon" :variant="item.variant" size="l" />
+            <span class="tw-text-sm">{{item.label}}</span>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Status icons with appropriate color variants to indicate product availability, order status, and other state information in e-commerce applications.",
+      },
+    },
+  },
+};
+
+export const IconTest: Story = {
+  render: () => ({
+    components: { VcIcon, VcIconTest },
+    template: `
+      <VcIconTest />
+    `,
+  }),
+};
+
+export const IconExamples: Story = {
+  render: () => ({
+    components: { VcIcon, VcIconExamples },
+    template: `
+      <VcIconExamples />
+    `,
+  }),
+};