@amedia/brick-mcp 0.0.2 → 0.1.1

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

@@ -0,0 +1,359 @@
+---
+name: brick-card
+version: 7.3.8
+selector: brick-card-v7
+category: Layout
+tags:
+  [
+    card,
+    container,
+    content-grouping,
+    layout,
+    flexible-container,
+    image-text,
+    article,
+  ]
+use_cases:
+  [
+    content-cards,
+    article-teasers,
+    product-listings,
+    call-to-action,
+    promotional-banners,
+    feature-highlights,
+    subscription-prompts,
+    tips-boxes,
+    step-by-step-guides,
+  ]
+related: [brick-button, brick-image, brick-stepper]
+---
+
+# Brick Card
+
+A flexible container component for grouping related content with support for images, text, buttons, and optional stepper functionality.
+
+## Key Capabilities
+
+- Highly flexible layout with horizontal and vertical orientations (including reverse directions)
+- Supports multiple visual themes (light, dark, alt, sport, highlight, custom)
+- Integrates brick-image and brick-button components seamlessly
+- Optional dense/compact layout modes for space efficiency
+- Primary and secondary button support with icons and ADP analytics tracking
+- Semantic HTML with configurable container tags (article or div)
+- Built-in support for brick-stepper to show progress
+- Meta itemprops for structured data and analytics
+
+## Props/Attributes
+
+| Attribute                         | Type                                                                                                        | Default     | Required | Description                                                                                              |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `data-skin`                       | `'none' \| 'black' \| 'custom-one' \| 'custom-two' \| 'sport' \| 'highlight' \| 'alt' \| 'dark' \| 'light'` | `'light'`   | No       | Visual theme/background color of the card                                                                |
+| `data-as`                         | `'article' \| 'div'`                                                                                        | `'article'` | No       | HTML tag to use for card container                                                                       |
+| `data-title-text`                 | `string`                                                                                                    | -           | No       | Main heading text                                                                                        |
+| `data-title-as`                   | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'`                                                              | `'h2'`      | No       | HTML heading level for title                                                                             |
+| `data-text`                       | `string`                                                                                                    | -           | No       | Body text content                                                                                        |
+| `data-primary-link-to`            | `string`                                                                                                    | -           | No       | URL for primary button                                                                                   |
+| `data-primary-button-text`        | `string`                                                                                                    | -           | No       | Text for primary button                                                                                  |
+| `data-primary-button-icon`        | `string`                                                                                                    | -           | No       | Icon name for primary button                                                                             |
+| `data-primary-button-adp-label`   | `string`                                                                                                    | -           | No       | ADP tracking label for primary button clicks                                                             |
+| `data-primary-button-adp-value`   | `string`                                                                                                    | -           | No       | ADP tracking value for primary button clicks                                                             |
+| `data-secondary-link-to`          | `string`                                                                                                    | -           | No       | URL for secondary button                                                                                 |
+| `data-secondary-button-text`      | `string`                                                                                                    | -           | No       | Text for secondary button                                                                                |
+| `data-secondary-button-icon`      | `string`                                                                                                    | -           | No       | Icon name for secondary button                                                                           |
+| `data-secondary-button-adp-label` | `string`                                                                                                    | -           | No       | ADP tracking label for secondary button clicks                                                           |
+| `data-secondary-button-adp-value` | `string`                                                                                                    | -           | No       | ADP tracking value for secondary button clicks                                                           |
+| `data-button-size`                | `'small' \| 'medium'`                                                                                       | `'medium'`  | No       | Size of buttons                                                                                          |
+| `data-image-src`                  | `string`                                                                                                    | -           | No       | Image source URL (use properly sized/encoded Reflex URLs)                                                |
+| `data-image-alt-text`             | `string`                                                                                                    | -           | No       | Alt text for image (required if image-src is provided)                                                   |
+| `data-image-size`                 | `'small' \| 'medium' \| 'large'`                                                                            | `'medium'`  | No       | Size of the image within the card                                                                        |
+| `data-layout`                     | `'default' \| 'compact'`                                                                                    | `'default'` | No       | Layout density (compact has tighter spacing and smaller fonts)                                           |
+| `data-layout-direction`           | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                    | `'row'`     | No       | Direction of content flow                                                                                |
+| `data-dense`                      | `boolean`                                                                                                   | `false`     | No       | Enable dense spacing mode                                                                                |
+| `data-meta-itemprops`             | `string`                                                                                                    | -           | No       | Meta element attributes as comma-separated key:value pairs (e.g., "adpType:teaser,contentModel:paywall") |
+| `data-steps`                      | `string`                                                                                                    | -           | No       | Number of steps for brick-stepper                                                                        |
+| `data-steps-current`              | `string`                                                                                                    | -           | No       | Current step for brick-stepper                                                                           |
+| `data-steps-completed`            | `string`                                                                                                    | -           | No       | Number of completed steps for brick-stepper                                                              |
+| `data-steps-order`                | `'asc' \| 'desc'`                                                                                           | `'asc'`     | No       | Order direction for steps                                                                                |
+| `data-steps-aria-label`           | `string`                                                                                                    | -           | No       | Aria label for stepper                                                                                   |
+| `data-steps-label`                | `string`                                                                                                    | -           | No       | Label text for steps                                                                                     |
+| `data-steps-icon-check`           | `string`                                                                                                    | -           | No       | Show check icon for completed steps                                                                      |
+| `data-steps-icon-lock`            | `string`                                                                                                    | -           | No       | Show lock icon for locked steps                                                                          |
+
+## Examples
+
+### Basic Card with Image and Title
+
+A simple horizontal card with an image and title.
+
+```html
+<brick-card-v7
+  data-image-src="https://g.acdn.no/api/reflex/v1/image/resize/680/https%3A%2F%2Fg.acdn.no%2Fobscura%2FAPI%2Fdynamic%2Fr1%2Fece5%2Ftr_2000_2000_s_f%2F0000%2Favio%2F2023%2F5%2F16%2F8%2F%252BHandwerk%252BBotaniske%252B-4151.jpg%3Fchk%3DDDB861"
+  data-image-alt-text="A happy waitress holding a breakfast tray"
+  data-title-text="Oppgrader og få frukost på din bursdag!"
+  data-skin="light"
+  data-image-size="large"
+>
+</brick-card-v7>
+```
+
+### Complete Card with All Features
+
+Full-featured card with image, title, text, and two buttons.
+
+```html
+<brick-card-v7
+  data-image-src="https://g.acdn.no/api/reflex/v1/image/resize/680/https%3A%2F%2Fg.acdn.no%2Fobscura%2FAPI%2Fdynamic%2Fr1%2Fece5%2Ftr_2000_2000_s_f%2F0000%2Favio%2F2023%2F5%2F16%2F8%2F%252BHandwerk%252BBotaniske%252B-4151.jpg%3Fchk%3DDDB861"
+  data-image-alt-text="A happy waitress holding a breakfast tray"
+  data-image-size="large"
+  data-title-text="Oppgrader og få frukost på din bursdag!"
+  data-text="Å spise frokost på kafé er en bra start på dagen enten du er en morgenfugl eller liker å sove lenge. Med +Alt får du alltid frukost på din bursdag!"
+  data-skin="light"
+  data-as="article"
+  data-primary-link-to="https://www.ao.no/stor-guide-lyst-pa-frokost-pa-kaf-her-er-13-steder-med-god-stemning/f/5-128-522696"
+  data-primary-button-text="Oppgrader til +Alt"
+  data-primary-button-icon="plusall"
+  data-button-size="small"
+  data-secondary-link-to="https://nn.wikipedia.org/wiki/Frukost"
+  data-secondary-button-text="Les mer om frukost"
+>
+</brick-card-v7>
+```
+
+### Vertical Layout Card
+
+Card with vertical content stacking (column layout).
+
+```html
+<brick-card-v7
+  data-layout-direction="column"
+  data-image-src="https://g.acdn.no/api/reflex/v1/image/resize/680/https%3A%2F%2Fg.acdn.no%2Fobscura%2FAPI%2Fdynamic%2Fr1%2Fece5%2Ftr_2000_2000_s_f%2F0000%2Favio%2F2023%2F5%2F16%2F8%2F%252BHandwerk%252BBotaniske%252B-4151.jpg%3Fchk%3DDDB861"
+  data-image-alt-text="A happy waitress holding a breakfast tray"
+  data-title-text="Vertical Card Example"
+  data-text="Content flows vertically in this layout."
+  data-skin="dark"
+  data-primary-link-to="/example"
+  data-primary-button-text="Learn More"
+>
+</brick-card-v7>
+```
+
+### Dense/Compact Card Without Image
+
+Minimal card for call-to-action boxes without images.
+
+```html
+<brick-card-v7
+  data-text="Vet du noe mer om denne saken?"
+  data-primary-link-to="/vis/info/tips-oss"
+  data-primary-button-text="Tips oss"
+  data-button-size="medium"
+  data-layout-direction="row"
+  data-dense="true"
+  data-skin="alt"
+>
+</brick-card-v7>
+```
+
+### Card with Stepper
+
+Card displaying progress through steps (e.g., for courses or multi-step processes).
+
+```html
+<brick-card-v7
+  data-layout-direction="column"
+  data-title-text="Complete Your Profile"
+  data-text="Follow these steps to complete your setup"
+  data-skin="light"
+  data-steps="7"
+  data-steps-current="3"
+  data-steps-label="Dag"
+  data-steps-order="desc"
+  data-steps-icon-check="true"
+  data-steps-icon-lock="true"
+  data-primary-link-to="/continue"
+  data-primary-button-text="Continue"
+>
+</brick-card-v7>
+```
+
+## Programmatic Usage
+
+### Client-Side Rendering
+
+```javascript
+import '@amedia/brick-card';
+
+const card = document.createElement('brick-card-v7');
+card.dataset.titleText = 'My Card Title';
+card.dataset.text = 'Card description text';
+card.dataset.imageSrc = 'https://example.com/image.jpg';
+card.dataset.imageAltText = 'Image description';
+card.dataset.primaryLinkTo = '/learn-more';
+card.dataset.primaryButtonText = 'Learn More';
+card.dataset.skin = 'light';
+
+document.body.appendChild(card);
+```
+
+### Server-Side Rendering
+
+```javascript
+import { renderBrickCard } from '@amedia/brick-card/template';
+
+const cardMarkup = renderBrickCard({
+  dataTitleText: 'Server-Rendered Card',
+  dataText: 'This card is rendered on the server',
+  dataImageSrc: 'https://example.com/image.jpg',
+  dataImageAltText: 'Image description',
+  dataPrimaryLinkTo: '/action',
+  dataPrimaryButtonText: 'Take Action',
+  dataSkin: 'dark',
+});
+
+// cardMarkup is a string of HTML ready to be sent to the client
+```
+
+## Accessibility
+
+- Semantic HTML: Use `data-as="article"` for self-contained content
+- Proper heading hierarchy: Configure `data-title-as` to match document structure
+- Image alt text: Always provide `data-image-alt-text` when using images
+- Keyboard navigation: All buttons are fully keyboard accessible
+- Screen reader support: Stepper component includes `data-steps-aria-label`
+- WCAG 2.1 AA compliant color contrast across all skin variants
+
+## Analytics Integration
+
+Brick-card supports ADP (Amedia Data Platform) analytics tracking for button clicks:
+
+```html
+<brick-card-v7
+  data-primary-button-text="Subscribe"
+  data-primary-link-to="/subscribe"
+  data-primary-button-adp-label="upgrade"
+  data-primary-button-adp-value="subscription-tier-premium"
+  data-secondary-button-text="Learn More"
+  data-secondary-link-to="/info"
+  data-secondary-button-adp-label="read-more"
+  data-secondary-button-adp-value="subscription-info"
+>
+</brick-card-v7>
+```
+
+**Important:** ADP logging requires wrapping the card with proper `itemscope` attributes. The card itself only renders the button labels; you must provide the ADP scope wrapper.
+
+## Common Patterns
+
+### Subscription/Upgrade Prompt
+
+For conversion-focused cards encouraging upgrades or subscriptions.
+
+```html
+<brick-card-v7
+  data-title-text="Upgrade to Premium"
+  data-text="Get unlimited access to all articles and exclusive content"
+  data-skin="highlight"
+  data-layout-direction="column"
+  data-primary-button-text="Upgrade Now"
+  data-primary-link-to="/subscribe"
+  data-primary-button-icon="plusall"
+  data-button-size="medium"
+>
+</brick-card-v7>
+```
+
+### Article Teaser
+
+For displaying article previews in lists or grids.
+
+```html
+<brick-card-v7
+  data-as="article"
+  data-image-src="https://example.com/article-image.jpg"
+  data-image-alt-text="Article preview image"
+  data-image-size="large"
+  data-title-text="Breaking News: Local Event Draws Crowds"
+  data-title-as="h3"
+  data-text="Thousands gathered downtown for the annual festival..."
+  data-skin="light"
+  data-primary-link-to="/article/12345"
+  data-primary-button-text="Read More"
+  data-meta-itemprops="adpType:teaser,contentModel:free"
+>
+</brick-card-v7>
+```
+
+### Tips/Help Box
+
+For contextual help or user engagement prompts.
+
+```html
+<brick-card-v7
+  data-text="Vet du noe mer om denne saken?"
+  data-skin="alt"
+  data-dense="true"
+  data-primary-link-to="/tips"
+  data-primary-button-text="Tips oss"
+  data-primary-button-adp-label="user-tips"
+>
+</brick-card-v7>
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-card-v7`
+- **Base Class**: BrickElement (from @amedia/brick-template)
+- **Dependencies**:
+  - @amedia/brick-template
+  - @amedia/brick-button
+  - @amedia/brick-image
+  - @amedia/brick-stepper
+  - @amedia/brick-tokens
+- **Renders as**: Configurable (`article` or `div`)
+- **Browser Support**: Modern browsers (ES2020+)
+- **Build Target**: ESM and CommonJS modules available
+
+## Important Notes
+
+### Image URLs
+
+Since brick-card v7.0.0 (brick-image v4), image URLs must be properly sized and encoded. Use Amedia's Reflex API:
+
+```
+https://g.acdn.no/api/reflex/v1/image/resize/680/[ENCODED_URL]
+```
+
+The size is not automatically applied; you must provide the correct size in the URL.
+
+### Breaking Changes from v6
+
+- `dataLinkTo` → `dataPrimaryLinkTo`
+- `dataButtonText` → `dataPrimaryButtonText`
+
+### Layout Flexibility
+
+The card does not require an image. You can create text-only cards by omitting `data-image-src`. Similarly, buttons are optional - omit button properties to create cards without actions.
+
+### Theme Inheritance
+
+Brick-card inherits theme context from parent elements. The `data-skin` attribute controls the card's background color within the inherited theme.
+
+### Meta Itemprops Format
+
+The `data-meta-itemprops` attribute accepts a comma-separated string of key:value pairs:
+
+```html
+data-meta-itemprops="adpType:teaser,contentModel:paywall,category:news"
+```
+
+This generates:
+
+```html
+<meta itemprop="adpType" content="teaser" />
+<meta itemprop="contentModel" content="paywall" />
+<meta itemprop="category" content="news" />
+```
+
+## Version
+
+Current version: 7.3.8