@amedia/brick-mcp 0.0.2 → 0.1.0

package/dist/data/components/brick-image.md

@@ -0,0 +1,361 @@
+---
+name: brick-image
+version: 6.0.5
+selector: brick-image-v6
+category: Media
+tags:
+  [image, responsive, lazy-loading, srcset, performance, media, picture, img]
+use_cases:
+  [
+    hero-section,
+    article-images,
+    product-listing,
+    image-gallery,
+    thumbnail,
+    teaser,
+    card,
+    banner,
+    media-content,
+    responsive-images,
+  ]
+related: [brick-button, brick-link, brick-card]
+---
+
+# Brick Image
+
+A responsive image component that wraps the native `<img>` element with support for modern image loading features including lazy loading, responsive images via srcset/sizes, and performance optimizations.
+
+## Key Capabilities
+
+- Native browser lazy loading with configurable `loading` attribute
+- Responsive image support through `srcset` and `sizes` attributes
+- Performance optimizations via `fetchpriority` and `decoding` attributes
+- Aspect ratio preservation using CSS custom properties
+- Server-side rendering support with `renderBrickImage()` function
+- Customizable styling through CSS variables (object-fit, dimensions, positioning)
+
+## Props/Attributes
+
+| Attribute             | Type                          | Default  | Required | Description                                                                                     |
+| --------------------- | ----------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `data-src`            | string                        | -        | yes      | The image source URL                                                                            |
+| `data-srcset`         | string                        | -        | no       | Responsive image source set (e.g., "image-400.jpg 400w, image-800.jpg 800w")                    |
+| `data-srcsize`        | string                        | -        | no       | Specific size for the src attribute (alternative to default sizing)                             |
+| `data-sizes`          | string                        | -        | no       | Media query conditions for responsive image selection (e.g., "(min-width: 800px) 800px, 100vw") |
+| `data-width`          | string                        | -        | no       | Intrinsic width of the image (sets width attribute on img)                                      |
+| `data-height`         | string                        | -        | no       | Intrinsic height of the image (sets height attribute on img)                                    |
+| `data-alt-text`       | string                        | `""`     | no       | Alternative text for accessibility                                                              |
+| `data-loading`        | `"eager" \| "lazy"`           | `"lazy"` | no       | Browser loading strategy                                                                        |
+| `data-fetch-priority` | `"high" \| "low" \| "auto"`   | `"auto"` | no       | Resource fetch priority hint                                                                    |
+| `data-decoding`       | `"async" \| "sync" \| "auto"` | `"auto"` | no       | Image decoding hint                                                                             |
+
+## Examples
+
+### Basic Image
+
+```html
+<brick-image-v6
+  data-src="https://example.com/image.jpg"
+  data-alt-text="A beautiful landscape"
+>
+</brick-image-v6>
+```
+
+### Responsive Image with Srcset
+
+```html
+<brick-image-v6
+  data-src="https://example.com/image-800.jpg"
+  data-srcset="https://example.com/image-400.jpg 400w,
+               https://example.com/image-800.jpg 800w,
+               https://example.com/image-1200.jpg 1200w"
+  data-sizes="(min-width: 1200px) 1200px, (min-width: 800px) 800px, 100vw"
+  data-alt-text="Product photo"
+>
+</brick-image-v6>
+```
+
+### Image with Aspect Ratio
+
+```html
+<brick-image-v6
+  data-src="https://example.com/image.jpg"
+  data-width="1600"
+  data-height="900"
+  data-alt-text="16:9 aspect ratio image"
+>
+</brick-image-v6>
+```
+
+### Eager Loading for Above-the-Fold Images
+
+```html
+<brick-image-v6
+  data-src="https://example.com/hero.jpg"
+  data-srcset="https://example.com/hero-800.jpg 800w,
+               https://example.com/hero-1600.jpg 1600w"
+  data-sizes="100vw"
+  data-loading="eager"
+  data-fetch-priority="high"
+  data-alt-text="Hero image"
+>
+</brick-image-v6>
+```
+
+### Lazy Loading for Below-the-Fold Images
+
+```html
+<brick-image-v6
+  data-src="https://example.com/thumbnail.jpg"
+  data-loading="lazy"
+  data-decoding="async"
+  data-alt-text="Thumbnail image"
+>
+</brick-image-v6>
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  let imageSrc = 'https://example.com/image.jpg';
+  let altText = 'Dynamic image';
+</script>
+
+<brick-image-v6
+  data-src={imageSrc}
+  data-alt-text={altText}
+  data-loading="lazy"
+/>
+```
+
+### React
+
+```jsx
+function MyComponent() {
+  return (
+    <brick-image-v6
+      data-src="https://example.com/image.jpg"
+      data-srcset="https://example.com/image-400.jpg 400w, https://example.com/image-800.jpg 800w"
+      data-sizes="(min-width: 800px) 800px, 100vw"
+      data-alt-text="Product image"
+      data-loading="lazy"
+    />
+  );
+}
+```
+
+## Programmatic Usage
+
+```javascript
+import { BrickImage } from '@amedia/brick-image';
+
+const imageElement = document.createElement('brick-image-v6');
+imageElement.dataSrc = 'https://example.com/image.jpg';
+imageElement.dataAltText = 'Programmatically created image';
+imageElement.dataLoading = 'lazy';
+document.body.appendChild(imageElement);
+```
+
+### Server-Side Rendering
+
+```javascript
+import { renderBrickImage } from '@amedia/brick-image/template';
+
+const html = renderBrickImage({
+  dataSrc: 'https://example.com/image.jpg',
+  dataSrcset:
+    'https://example.com/image-400.jpg 400w, https://example.com/image-800.jpg 800w',
+  dataSizes: '(min-width: 800px) 800px, 100vw',
+  dataWidth: '1600',
+  dataHeight: '900',
+  dataAltText: 'Server-rendered image',
+  dataLoading: 'lazy',
+});
+
+// Returns:
+// <brick-image-v6 is-rendered brick-component="brick-image" class="..." data-src="..." ...>
+//   <img src="..." srcset="..." sizes="..." width="1600" height="900" alt="..." loading="lazy" class="..." style="--brick-image-ratio: 1600 / 900;">
+// </brick-image-v6>
+```
+
+## Styling with CSS Variables
+
+The component exposes several CSS variables for customization:
+
+```css
+brick-image-v6 {
+  /* Dimensions */
+  --brick-image-width: 100%;
+  --brick-image-height: auto;
+  --brick-image-maxwidth: 100%;
+  --brick-image-maxheight: auto;
+
+  /* Object positioning and fit */
+  --brick-image-objectfit: cover;
+  --brick-image-objectposition: center;
+
+  /* Background (visible while loading) */
+  --brick-image-color-bg: transparent;
+
+  /* Sizes attribute (alternative to data-sizes) */
+  --brick-image-sizes: (min-width: 800px) 800px, 100vw;
+}
+```
+
+### Example: Custom Styling
+
+```html
+<style>
+  .hero-image {
+    --brick-image-width: 100%;
+    --brick-image-height: 60vh;
+    --brick-image-objectfit: cover;
+    --brick-image-objectposition: center top;
+  }
+
+  .thumbnail {
+    --brick-image-width: 200px;
+    --brick-image-height: 200px;
+    --brick-image-objectfit: contain;
+    --brick-image-color-bg: #f0f0f0;
+  }
+</style>
+
+<brick-image-v6
+  class="hero-image"
+  data-src="https://example.com/hero.jpg"
+  data-alt-text="Hero image"
+>
+</brick-image-v6>
+
+<brick-image-v6
+  class="thumbnail"
+  data-src="https://example.com/thumb.jpg"
+  data-alt-text="Thumbnail"
+>
+</brick-image-v6>
+```
+
+## Accessibility
+
+- Always provide meaningful `data-alt-text` for screen readers
+- For decorative images, use empty alt text: `data-alt-text=""`
+- Aspect ratio preservation prevents layout shift (CLS) when `data-width` and `data-height` are provided
+- Native lazy loading reduces initial page load for better user experience
+
+## Common Patterns
+
+### Hero Section Image
+
+Large, above-the-fold images should use eager loading with high priority:
+
+```html
+<brick-image-v6
+  data-src="https://example.com/hero-1600.jpg"
+  data-srcset="https://example.com/hero-800.jpg 800w,
+               https://example.com/hero-1600.jpg 1600w,
+               https://example.com/hero-2400.jpg 2400w"
+  data-sizes="100vw"
+  data-width="1600"
+  data-height="600"
+  data-loading="eager"
+  data-fetch-priority="high"
+  data-alt-text="Welcome to our store"
+  style="--brick-image-objectfit: cover; --brick-image-height: 60vh;"
+>
+</brick-image-v6>
+```
+
+### Product Listing Thumbnails
+
+Grid of images with consistent aspect ratios:
+
+```html
+<brick-image-v6
+  data-src="https://example.com/product.jpg"
+  data-srcset="https://example.com/product-400.jpg 400w,
+               https://example.com/product-800.jpg 800w"
+  data-sizes="(min-width: 768px) 33vw, 50vw"
+  data-width="800"
+  data-height="800"
+  data-loading="lazy"
+  data-decoding="async"
+  data-alt-text="Product name"
+  style="--brick-image-objectfit: cover;"
+>
+</brick-image-v6>
+```
+
+### Article Images
+
+Content images with natural aspect ratios:
+
+```html
+<brick-image-v6
+  data-src="https://example.com/article-image.jpg"
+  data-srcset="https://example.com/article-image-600.jpg 600w,
+               https://example.com/article-image-1200.jpg 1200w"
+  data-sizes="(min-width: 1200px) 800px, (min-width: 768px) 600px, 100vw"
+  data-width="1200"
+  data-height="800"
+  data-loading="lazy"
+  data-alt-text="Description of the image content"
+>
+</brick-image-v6>
+```
+
+### Using CSS Variable for Sizes
+
+Instead of `data-sizes`, you can use the CSS variable approach:
+
+```html
+<style>
+  .responsive-image {
+    --brick-image-sizes: (min-width: 1024px) 800px, (min-width: 768px) 600px,
+      100vw;
+  }
+</style>
+
+<brick-image-v6
+  class="responsive-image"
+  data-src="https://example.com/image.jpg"
+  data-srcset="https://example.com/image-600.jpg 600w,
+               https://example.com/image-800.jpg 800w,
+               https://example.com/image-1200.jpg 1200w"
+  data-alt-text="Responsive image"
+>
+</brick-image-v6>
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-image-v6`
+- **Base Class**: BrickElement (from @amedia/brick-template)
+- **Dependencies**: @amedia/brick-tokens, @amedia/brick-template
+- **Renders as**: Custom element wrapping an `<img>` tag
+- **Browser Support**: Modern browsers with Web Components support
+- **Package**: @amedia/brick-image
+
+## Important Notes
+
+- The component does NOT generate srcset automatically. You must provide the correct `data-srcset` value for responsive images.
+- Image URLs are used as-is; no automatic resizing or transformation is applied by the component.
+- When both `data-width` and `data-height` are provided, the component sets the `aspect-ratio` CSS property for browsers that support it.
+- The `data-srcsize` attribute is for cases where you need to specify a different size variant for the `src` attribute.
+- For server-side rendering, use the `renderBrickImage()` function from the `/template` export, which returns the full HTML string including the custom element wrapper.
+- The component uses native browser lazy loading (`loading="lazy"`), which is well-supported in modern browsers.
+- CSS variables prefixed with `--brick-image-` can be used to customize the component's appearance without modifying the component itself.
+
+## Version
+
+Current version: 6.0.5
+
+### Recent Changes
+
+- **6.0.4**: Improved types for `dataLoading`, `dataFetchPriority`, `dataDecoding`
+- **6.0.0**: Removed legacy `<amedia-img>` custom element export
+- **5.0.0**: Removed CommonJS support (ESM only)
+- **4.0.11**: Added `data-decoding` attribute support