@repobit/dex-system-design 0.22.12 → 0.23.1

package/src/components/image/image.stories.js

@@ -1,92 +1,95 @@
 import { html } from 'lit';
-import '../heading/heading.js';
-import '../paragraph/paragraph.js';
 import './image.js';
 
 export default {
-  title    : 'Atoms/Image',
-  component: 'bd-img',
-  tags     : ['autodocs'],
-  argTypes : {
+  title     : 'Components/Image',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdImg** is a Lit image component with fit, radius, shadow, and loading configuration.
+
+### Usage
+\`\`\`html
+<bd-img
+  src="/assets/product.png"
+  alt="Product screenshot"
+  width="800"
+  height="600"
+  fit="cover"
+  radius="md"
+  shadow="lg"
+  loading="lazy"
+></bd-img>
+\`\`\`
+
+### CSS Classes Applied
+| Prop | Class Pattern |
+|---|---|
+| \`fit\` | value used directly (e.g. \`cover\`, \`contain\`) |
+| \`radius\` | \`radius-{value}\` (e.g. \`radius-none\`, \`radius-md\`) |
+| \`shadow\` | \`shadow-{value}\` (e.g. \`shadow-none\`, \`shadow-lg\`) |
+
+### Events
+- \`image-loaded\` — fired on successful image load
+- \`image-error\` — fired when the image fails to load
+        `
+      }
+    }
+  },
+  argTypes: {
     src: {
       control    : 'text',
-      description: 'Image source URL or path',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '' }
-      }
+      description: 'Image source URL',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
     alt: {
       control    : 'text',
-      description: 'Alternative text for accessibility and SEO',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '' }
-      }
+      description: 'Alt text for accessibility',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
     width: {
       control    : 'number',
-      description: 'Image width in pixels',
-      table      : {
-        type        : { summary: 'number' },
-        defaultValue: { summary: 'auto' }
-      }
+      description: 'Intrinsic width of the image',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Dimensions' }
     },
     height: {
       control    : 'number',
-      description: 'Image height in pixels',
-      table      : {
-        type        : { summary: 'number' },
-        defaultValue: { summary: 'auto' }
-      }
+      description: 'Intrinsic height of the image',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Dimensions' }
     },
     loading: {
       control    : { type: 'select' },
       options    : ['lazy', 'eager'],
-      description: 'Image loading strategy',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'lazy' }
-      }
+      description: 'Native browser loading strategy',
+      table      : { type: { summary: "'lazy' | 'eager'" }, defaultValue: { summary: 'lazy' }, category: 'Performance' }
     },
     fit: {
       control    : { type: 'select' },
       options    : ['cover', 'contain', 'fill', 'none', 'scale-down'],
-      description: 'How the image should be resized to fit its container',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'cover' }
-      }
+      description: 'Object-fit behavior applied as a CSS class',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'cover' }, category: 'Appearance' }
     },
     radius: {
       control    : { type: 'select' },
-      options    : ['none', 'sm', 'md', 'lg', 'full'],
-      description: 'Border radius for rounded corners',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'none' }
-      }
+      options    : ['none', 'sm', 'md', 'lg', 'xl', 'full'],
+      description: 'Border radius applied as `radius-{value}` class',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'none' }, category: 'Appearance' }
     },
     shadow: {
       control    : { type: 'select' },
-      options    : ['none', 'sm', 'md', 'lg'],
-      description: 'Box shadow for depth effect',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'none' }
-      }
-    }
-  },
-  parameters: {
-    docs: {
-      description: {
-        component: 'An enhanced image component with built-in styling options, loading strategies, and accessibility features. Provides consistent image handling across the application with performance optimizations.'
-      }
+      options    : ['none', 'sm', 'md', 'lg', 'xl'],
+      description: 'Box shadow applied as `shadow-{value}` class',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'none' }, category: 'Appearance' }
     }
   }
 };
 
-const Template = (args) => html`
+const sampleSrc = 'https://via.placeholder.com/800x450';
+const defaultArgs = { src: sampleSrc, alt: 'Sample image', width: 800, height: 450, loading: 'lazy', fit: 'cover', radius: 'none', shadow: 'none' };
+
+const render = (args) => html`
   <bd-img
     src="${args.src}"
     alt="${args.alt}"
@@ -99,533 +102,102 @@ const Template = (args) => html`
   ></bd-img>
 `;
 
-// ============ STORIES ============
+// ─── Stories ───────────────────────────────────────────────────────────────
 
-export const Default = Template.bind({});
-Default.args = {
-  src    : '/assets/bd-header-us.jpg',
-  alt    : 'Bitdefender Security Illustration',
-  width  : 400,
-  height : 250,
-  loading: 'lazy',
-  fit    : 'cover',
-  radius : 'none',
-  shadow : 'none'
-};
-Default.parameters = {
-  docs: {
-    description: {
-      story: 'Default image component with standard configuration. Uses lazy loading and cover fit for optimal performance and appearance.'
-    }
-  }
+export const Default = {
+  name      : 'Default',
+  render    : () => html`<bd-img src="${sampleSrc}" alt="Sample image" width="800" height="450"></bd-img>`,
+  parameters: { docs: { description: { story: 'Default image with `fit="cover"`, `radius="none"`, `shadow="none"`, and `loading="lazy"`.' } } }
 };
 
-export const AllObjectFitOptions = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 900px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Object Fit Property Examples</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      The object-fit property defines how an image should be resized to fit its container. Each option has specific use cases and behaviors.
-    </bd-p>
-    
-    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem;">
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Cover</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Cover fit example"
-            width="250"
-            height="200"
-            fit="cover"
-          ></bd-img>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Hero images, profile pictures<br>
-          <strong>Behavior:</strong> Fills entire container, may crop edges<br>
-          <strong>Best for:</strong> Maintaining aspect ratio while filling space
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Contain</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden; background: #f8fafc;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Contain fit example"
-            width="250"
-            height="200"
-            fit="contain"
-          ></bd-img>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Product images, logos<br>
-          <strong>Behavior:</strong> Fits entirely within container, may have empty space<br>
-          <strong>Best for:</strong> Showing complete image without cropping
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Fill</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Fill fit example"
-            width="250"
-            height="200"
-            fit="fill"
-          ></bd-img>
+export const FitVariants = {
+  name  : 'Fit Variants',
+  render: () => html`
+    <div style="display:flex; gap:16px; flex-wrap:wrap;">
+      ${['cover', 'contain', 'fill', 'none', 'scale-down'].map(fit => html`
+        <div>
+          <p style="font-size:12px; margin-bottom:4px; font-weight:600;">${fit}</p>
+          <bd-img src="${sampleSrc}" alt="${fit}" width="200" height="150" fit="${fit}"></bd-img>
         </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Background patterns, decorative images<br>
-          <strong>Behavior:</strong> Stretches to fill container, may distort<br>
-          <strong>Best for:</strong> When aspect ratio preservation isn't important
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">None</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="None fit example"
-            width="250"
-            height="200"
-            fit="none"
-          ></bd-img>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Icons, small graphics<br>
-          <strong>Behavior:</strong> Original size, may overflow container<br>
-          <strong>Best for:</strong> When you need the original image dimensions
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Scale Down</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden; background: #f8fafc;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Scale down fit example"
-            width="250"
-            height="200"
-            fit="scale-down"
-          ></bd-img>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Responsive images, variable content<br>
-          <strong>Behavior:</strong> Like contain, but never scales up<br>
-          <strong>Best for:</strong> Preventing pixelation on large containers
-        </bd-p>
-      </div>
+      `)}
     </div>
-  </div>
-`;
-AllObjectFitOptions.parameters = {
-  docs: {
-    description: {
-      story: 'Comprehensive demonstration of all object-fit property options with detailed explanations of when to use each option and their specific behaviors in different layout scenarios.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'All five `fit` values: cover, contain, fill, none, scale-down.' } } }
 };
 
-export const LoadingStrategies = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Image Loading Strategies</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Choose the right loading strategy based on image importance and position on the page to optimize performance and user experience.
-    </bd-p>
-    
-    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); gap: 2rem;">
-      <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-        <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Lazy Loading</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Lazy loaded security image"
-          width="300"
-          height="200"
-          loading="lazy"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>When to use:</strong> Images below the fold, gallery items, non-critical content<br>
-          <strong>Performance:</strong> Improves page load time by deferring off-screen images<br>
-          <strong>User experience:</strong> Smooth scrolling with images loading as needed
-        </bd-p>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          💡 <strong>Best practice:</strong> Use for all images that aren't immediately visible
-        </bd-p>
-      </div>
-      
-      <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-        <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Eager Loading</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Eager loaded security image"
-          width="300"
-          height="200"
-          loading="eager"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>When to use:</strong> Hero images, above-the-fold content, critical visuals<br>
-          <strong>Performance:</strong> Loads immediately, may impact initial page load<br>
-          <strong>User experience:</strong> Important images are ready when page renders
-        </bd-p>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          ⚠️ <strong>Use sparingly:</strong> Only for images essential to initial page rendering
-        </bd-p>
-      </div>
+export const RadiusVariants = {
+  name  : 'Radius Variants',
+  render: () => html`
+    <div style="display:flex; gap:16px; flex-wrap:wrap;">
+      ${['none', 'sm', 'md', 'lg', 'xl', 'full'].map(r => html`
+        <div>
+          <p style="font-size:12px; margin-bottom:4px; font-weight:600;">radius-${r}</p>
+          <bd-img src="${sampleSrc}" alt="radius ${r}" width="150" height="150" radius="${r}" fit="cover"></bd-img>
+        </div>
+      `)}
     </div>
-  </div>
-`;
-LoadingStrategies.parameters = {
-  docs: {
-    description: {
-      story: 'Comparison of lazy vs eager loading strategies with performance implications and guidelines for when to use each approach based on image importance and page position.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'All radius values: none, sm, md, lg, xl, full — applied as `radius-{value}` CSS class.' } } }
 };
 
-export const StylingVariants = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 1000px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Styling and Appearance Variants</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Customize the appearance of images with border radius and shadow options to match your design system and create visual hierarchy.
-    </bd-p>
-    
-    <div>
-      <bd-h as="h3" style="margin-bottom: 2rem; color: #3b82f6;">Border Radius Options</bd-h>
-      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 2rem;">
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="No border radius"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="none"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>None</strong><br>
-            Square corners
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Small border radius"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="sm"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Small</strong><br>
-            Subtle rounding
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Medium border radius"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="md"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Medium</strong><br>
-            Balanced rounding
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Large border radius"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="lg"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Large</strong><br>
-            Prominent rounding
-          </bd-p>
+export const ShadowVariants = {
+  name  : 'Shadow Variants',
+  render: () => html`
+    <div style="display:flex; gap:24px; flex-wrap:wrap; padding:16px;">
+      ${['none', 'sm', 'md', 'lg', 'xl'].map(s => html`
+        <div>
+          <p style="font-size:12px; margin-bottom:8px; font-weight:600;">shadow-${s}</p>
+          <bd-img src="${sampleSrc}" alt="shadow ${s}" width="180" height="120" shadow="${s}" radius="md"></bd-img>
         </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Full border radius"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="full"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Full</strong><br>
-            Circular/oval shape
-          </bd-p>
-        </div>
-      </div>
-    </div>
-    
-    <div>
-      <bd-h as="h3" style="margin-bottom: 2rem; color: #3b82f6;">Shadow Options</bd-h>
-      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 2rem;">
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="No shadow"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="md"
-            shadow="none"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>None</strong><br>
-            Flat appearance
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Small shadow"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="md"
-            shadow="sm"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Small</strong><br>
-            Subtle elevation
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Medium shadow"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="md"
-            shadow="md"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Medium</strong><br>
-            Noticeable depth
-          </bd-p>
-        </div>
-        
-        <div style="text-align: center;">
-          <bd-img
-            src="/assets/bd-header-us.jpg"
-            alt="Large shadow"
-            width="150"
-            height="100"
-            fit="cover"
-            radius="md"
-            shadow="lg"
-          ></bd-img>
-          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-            <strong>Large</strong><br>
-            Prominent elevation
-          </bd-p>
-        </div>
-      </div>
+      `)}
     </div>
-  </div>
-`;
-StylingVariants.parameters = {
-  docs: {
-    description: {
-      story: 'Comprehensive showcase of styling options including border radius variations (none, small, medium, large, full) and shadow effects (none, small, medium, large) to create different visual appearances and depth effects.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Shadow levels from none to xl — applied as `shadow-{value}` CSS class.' } } }
 };
 
-export const AccessibilityExamples = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Accessibility Best Practices</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Proper image accessibility ensures that all users, including those using screen readers, can understand and interact with your content effectively.
-    </bd-p>
-    
-    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); gap: 2rem;">
-      <div style="border: 2px solid #10b981; padding: 2rem; border-radius: 12px; background: #f0fdf4;">
-        <bd-h as="h3" style="color: #059669; margin-bottom: 1rem;">✅ Good Alt Text</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Bitdefender security software interface showing real-time threat protection dashboard"
-          width="300"
-          height="200"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>Descriptive:</strong> Clearly describes the image content and context<br>
-          <strong>Concise:</strong> Brief but meaningful (125 characters or less)<br>
-          <strong>Relevant:</strong> Relates to the surrounding content
-        </bd-p>
-        <bd-p kind="small" style="color: #059669; margin-top: 1rem;">
-          ✅ Screen readers will read: "Bitdefender security software interface showing real-time threat protection dashboard"
-        </bd-p>
-      </div>
-      
-      <div style="border: 2px solid #ef4444; padding: 2rem; border-radius: 12px; background: #fef2f2;">
-        <bd-h as="h3" style="color: #dc2626; margin-bottom: 1rem;">❌ Poor Alt Text</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="image123.jpg"
-          width="300"
-          height="200"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>File names:</strong> Never use file names as alt text<br>
-          <strong>Placeholders:</strong> Avoid generic text like "image" or "photo"<br>
-          <strong>Redundancy:</strong> Don't start with "image of" or "picture of"
-        </bd-p>
-        <bd-p kind="small" style="color: #dc2626; margin-top: 1rem;">
-          ❌ Screen readers will read: "image123.jpg" - meaningless to users
-        </bd-p>
-      </div>
-    </div>
-    
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Decorative Images</bd-h>
-      <bd-p kind="regular" style="margin-bottom: 1.5rem;">
-        For purely decorative images that don't convey meaningful content, use empty alt text to prevent screen readers from announcing them.
-      </bd-p>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt=""
-        width="300"
-        height="100"
-        fit="cover"
-        radius="md"
-      ></bd-img>
-      <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-        ✅ Empty alt attribute: <code>alt=""</code> - Screen readers will skip this image entirely
-      </bd-p>
-    </div>
-  </div>
-`;
-AccessibilityExamples.parameters = {
-  docs: {
-    description: {
-      story: 'Accessibility guidelines and examples showing proper alt text usage, common mistakes to avoid, and how to handle decorative images. Essential for creating inclusive experiences for screen reader users.'
-    }
-  }
+export const LazyLoading = {
+  name  : 'Lazy Loading',
+  render: () => html`
+    <bd-img src="${sampleSrc}" alt="Lazy loaded" width="800" height="450" loading="lazy"></bd-img>
+  `,
+  parameters: { docs: { description: { story: '`loading="lazy"` — default. The browser defers loading until the image is near the viewport.' } } }
 };
 
-export const ResponsiveSizes = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Responsive Size Examples</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Images should adapt to different screen sizes and layout requirements. Here are common size patterns for various use cases.
-    </bd-p>
-    
-    <div style="display: flex; flex-direction: column; gap: 2rem;">
-      <div>
-        <bd-h as="h4" style="margin-bottom: 1rem;">Small (400px) - Thumbnails & Icons</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Small security image for thumbnails"
-          width="400"
-          height="250"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          Ideal for product thumbnails, user avatars, and icon-sized images in lists and grids.
-        </bd-p>
-      </div>
-      
-      <div>
-        <bd-h as="h4" style="margin-bottom: 1rem;">Medium (600px) - Content Images</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Medium security image for content"
-          width="600"
-          height="375"
-          fit="cover"
-          radius="md"
-        ></bd-img>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          Perfect for blog posts, article content, and feature sections within page layouts.
-        </bd-p>
-      </div>
-      
-      <div>
-        <bd-h as="h4" style="margin-bottom: 1rem;">Large (750px) - Hero & Header Images</bd-h>
-        <bd-img
-          src="/assets/bd-header-us.jpg"
-          alt="Large security image for hero sections"
-          width="750"
-          height="500"
-          fit="cover"
-          radius="none"
-        ></bd-img>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          Designed for hero sections, header images, and prominent visual elements that need maximum impact.
-        </bd-p>
-      </div>
-    </div>
-  </div>
-`;
-ResponsiveSizes.parameters = {
-  docs: {
-    description: {
-      story: 'Common image size patterns for different use cases including thumbnails (small), content images (medium), and hero images (large) with recommendations for when to use each size category.'
-    }
-  }
+export const EagerLoading = {
+  name  : 'Eager Loading',
+  render: () => html`
+    <bd-img src="${sampleSrc}" alt="Eagerly loaded" width="800" height="450" loading="eager"></bd-img>
+  `,
+  parameters: { docs: { description: { story: '`loading="eager"` — image loads immediately regardless of viewport position.' } } }
 };
 
-export const HeaderImageExample = Template.bind({});
-HeaderImageExample.args = {
-  src    : '/assets/bd-header-us.jpg',
-  alt    : 'Bitdefender Ultimate Security Header - Advanced threat protection dashboard with real-time monitoring',
-  width  : 750,
-  height : 500,
-  loading: 'eager',
-  fit    : 'cover',
-  radius : 'none',
-  shadow : 'none'
+export const RoundedWithShadow = {
+  name  : 'Rounded + Shadow',
+  render: () => html`
+    <bd-img src="${sampleSrc}" alt="Styled image" width="600" height="400" radius="lg" shadow="lg" fit="cover"></bd-img>
+  `,
+  parameters: { docs: { description: { story: 'Combined `radius="lg"` and `shadow="lg"` for a polished card-style image.' } } }
 };
-HeaderImageExample.parameters = {
-  docs: {
-    description: {
-      story: 'Example of a header image configuration with eager loading (for above-the-fold content), cover fit to fill the container, and descriptive alt text for accessibility.'
-    }
-  }
+
+export const CircleImage = {
+  name  : 'Circle Image (radius full)',
+  render: () => html`
+    <bd-img src="${sampleSrc}" alt="Avatar" width="200" height="200" radius="full" fit="cover"></bd-img>
+  `,
+  parameters: { docs: { description: { story: 'Equal width/height with `radius="full"` creates a circular avatar-style image.' } } }
 };
 
-export const InteractivePlayground = Template.bind({});
-InteractivePlayground.args = {
-  src    : '/assets/bd-header-us.jpg',
-  alt    : 'Customizable image example',
-  width  : 400,
-  height : 250,
-  loading: 'lazy',
-  fit    : 'cover',
-  radius : 'none',
-  shadow : 'none'
+export const ErrorState = {
+  name  : 'Error State (broken src)',
+  render: () => html`
+    <bd-img src="/nonexistent-image.png" alt="Broken image" width="400" height="300"></bd-img>
+  `,
+  parameters: { docs: { description: { story: 'Image with a broken `src`. The `image-error` custom event is dispatched. The browser renders its default broken image indicator.' } } }
 };
-InteractivePlayground.parameters = {
-  docs: {
-    description: {
-      story: 'Interactive playground where you can test all image properties in real-time. Use the controls panel to modify the image source, dimensions, loading strategy, fit behavior, and styling options.'
-    }
-  }
+
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { ...defaultArgs },
+  render,
+  parameters: { docs: { description: { story: 'Fully interactive. Adjust all props via Controls.' } } }
 };