@amedia/brick-mcp 0.0.1-LLM-DOCS → 0.0.1-NEW-PATH-1

package/data/components/brick-image.md

@@ -1,335 +0,0 @@
----
-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