@amedia/brick-mcp 0.0.2 → 0.1.1

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

@@ -0,0 +1,355 @@
+---
+name: brick-carousel
+version: 2.0.10
+selector: brick-carousel-v2
+category: Layout
+tags:
+  [
+    carousel,
+    slider,
+    content-slider,
+    gallery,
+    navigation,
+    scroll,
+    responsive,
+    accessible,
+  ]
+use_cases:
+  [
+    content-carousels,
+    image-galleries,
+    article-sliders,
+    video-carousels,
+    product-listings,
+    teaser-collections,
+    media-galleries,
+    responsive-layouts,
+  ]
+related: [brick-teaser, brick-image, brick-player]
+---
+
+# Brick Carousel
+
+A simple, accessible carousel component for displaying any type of content in a horizontal scrolling layout with navigation controls.
+
+## Key Capabilities
+
+- Fully accessible with semantic markup, keyboard navigation, and ARIA support
+- Supports three layout types: carousel (default), gallery (full-width single items), and compact (dense layout)
+- Responsive design that adapts to container width (1-3 items visible depending on space)
+- Client-side and server-side rendering support
+- Drag-to-scroll functionality on desktop
+- Automatic mutation detection for dynamically added content
+- Template tag support for custom elements to prevent early initialization
+- Customizable navigation button visibility
+
+## Props/Attributes
+
+| Attribute                 | Type                                   | Default      | Required         | Description                                                                                                                  |
+| ------------------------- | -------------------------------------- | ------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `data-version`            | `"carousel" \| "gallery" \| "compact"` | `"carousel"` | No               | Layout type. "carousel" shows 1-3 items, "gallery" shows 1 full-width item, "compact" provides a denser layout               |
+| `data-min-slides-to-show` | `string` (number)                      | `"1"`        | No               | Minimum number of slides to show. When set to "2" and only 2 children exist, shows both in a fraction grid without scrolling |
+| `data-hide-btn-start-end` | `boolean`                              | `false`      | No               | Hides navigation buttons when at start/end of carousel. Not recommended for content wrapped in links to avoid misclicks      |
+| `dataItems`               | `string[]`                             | -            | No (Yes for SSR) | Array of HTML content strings for server-side rendering. Each item is automatically wrapped with proper `<li>` markup        |
+
+## Examples
+
+### Basic Carousel (Client-side)
+
+```html
+<script
+  type="module"
+  src="https://assets.acdn.no/pkg/@amedia/brick-carousel/2.0.10/brick-carousel.js"
+></script>
+
+<brick-carousel-v2>
+  <article>Article 1 content</article>
+  <article>Article 2 content</article>
+  <article>Article 3 content</article>
+  <article>Article 4 content</article>
+  <article>Article 5 content</article>
+</brick-carousel-v2>
+```
+
+### Gallery Mode
+
+Shows one full-width item at a time, ideal for image galleries.
+
+```html
+<brick-carousel-v2 data-version="gallery">
+  <brick-image-v9
+    src="https://example.com/image1.jpg"
+    alt="Image 1"
+  ></brick-image-v9>
+  <brick-image-v9
+    src="https://example.com/image2.jpg"
+    alt="Image 2"
+  ></brick-image-v9>
+  <brick-image-v9
+    src="https://example.com/image3.jpg"
+    alt="Image 3"
+  ></brick-image-v9>
+</brick-carousel-v2>
+```
+
+### Compact Layout
+
+Provides a denser layout with adjusted grid column widths.
+
+```html
+<brick-carousel-v2 data-version="compact">
+  <brick-teaser-v13 title="Compact teaser 1"></brick-teaser-v13>
+  <brick-teaser-v13 title="Compact teaser 2"></brick-teaser-v13>
+  <brick-teaser-v13 title="Compact teaser 3"></brick-teaser-v13>
+  <brick-teaser-v13 title="Compact teaser 4"></brick-teaser-v13>
+</brick-carousel-v2>
+```
+
+### Minimum Slides to Show
+
+Forces minimum 2 slides visible even on smaller screens. When exactly 2 children exist, displays both without navigation.
+
+```html
+<brick-carousel-v2 data-min-slides-to-show="2">
+  <article>Article 1</article>
+  <article>Article 2</article>
+</brick-carousel-v2>
+```
+
+### Using Template Tags for Custom Elements
+
+Wrap content in `<template>` tags to prevent custom elements (like brick-player) from initializing too early. The template content is added to the DOM after being placed in the carousel.
+
+```html
+<brick-carousel-v2>
+  <template>
+    <brick-player
+      mediaid="abc123"
+      playerid="xyz789"
+      aspectratio="16:9"
+      title="Video title"
+    >
+    </brick-player>
+  </template>
+  <template>
+    <brick-player
+      mediaid="def456"
+      playerid="xyz789"
+      aspectratio="16:9"
+      title="Another video"
+    >
+    </brick-player>
+  </template>
+</brick-carousel-v2>
+```
+
+## Server-Side Rendering
+
+### Basic SSR Example
+
+```typescript
+import { renderBrickCarousel } from '@amedia/brick-carousel/template';
+
+const carouselHTML = renderBrickCarousel({
+  dataItems: [
+    '<article>Article 1</article>',
+    '<article>Article 2</article>',
+    '<article>Article 3</article>',
+    '<article>Article 4</article>',
+  ],
+  dataVersion: 'carousel',
+  dataMinSlidesToShow: '2',
+});
+```
+
+### SSR Gallery Example
+
+```typescript
+import { renderBrickCarousel } from '@amedia/brick-carousel/template';
+
+const galleryHTML = renderBrickCarousel({
+  dataItems: [
+    '<brick-image-v9 src="image1.jpg" alt="Image 1"></brick-image-v9>',
+    '<brick-image-v9 src="image2.jpg" alt="Image 2"></brick-image-v9>',
+    '<brick-image-v9 src="image3.jpg" alt="Image 3"></brick-image-v9>',
+  ],
+  dataVersion: 'gallery',
+});
+```
+
+### SSR with Hide Buttons
+
+```typescript
+import { renderBrickCarousel } from '@amedia/brick-carousel/template';
+
+const carouselHTML = renderBrickCarousel({
+  dataItems: [
+    '<div class="content">Slide 1</div>',
+    '<div class="content">Slide 2</div>',
+    '<div class="content">Slide 3</div>',
+  ],
+  dataHideBtnStartEnd: true,
+});
+```
+
+## Programmatic Usage
+
+```javascript
+import { BrickCarousel } from '@amedia/brick-carousel';
+
+const carousel = new BrickCarousel({
+  dataVersion: 'carousel',
+  dataMinSlidesToShow: '2',
+  dataHideBtnStartEnd: false,
+});
+
+// Append to DOM
+document.querySelector('#container').appendChild(carousel);
+
+// Add items dynamically
+const article = document.createElement('article');
+article.textContent = 'Dynamic content';
+carousel.appendChild(article);
+```
+
+## Accessibility
+
+### Built-in Accessibility Features
+
+- **Semantic HTML**: Uses `<section>`, `<ul>`, and `<li>` elements with proper ARIA roles
+- **Screen Reader Support**:
+  - `aria-describedby` connects carousel to descriptive text
+  - Each slide announces "Article X of Y" (or "Image X of Y" for gallery mode)
+  - Skip link allows users to bypass carousel content
+- **Keyboard Navigation**:
+  - `Arrow Left/Right`: Navigate between slides
+  - `Tab`: Navigate through focusable elements within slides
+  - `Escape`: Skip to content after carousel
+- **Navigation Buttons**: Properly labeled with `aria-label` and disabled states
+- **Reduced Motion**: Respects `prefers-reduced-motion` user preference
+- **Focus Management**: Automatically manages focus when navigating to start/end
+
+### WCAG 2.1 AA Compliance
+
+Component is tested for accessibility and meets WCAG 2.1 AA standards with automated axe tests via Playwright.
+
+## Responsive Behavior
+
+The carousel automatically adjusts the number of visible slides based on container width:
+
+- **< 460px**: Shows 1 slide
+- **460px - 768px**: Shows 2 slides
+- **> 768px**: Shows 3 slides (or fewer if `data-slides` is less than 3)
+- **Gallery mode**: Always shows 1 full-width slide
+- **When `data-min-slides-to-show="2"`**: Forces minimum 2 slides visible
+
+## Styling and CSS Properties
+
+### Custom CSS Properties
+
+| Property                    | Description                                                | Default           |
+| --------------------------- | ---------------------------------------------------------- | ----------------- |
+| `--b-carousel-btn-min`      | Minimum width and height for navigation buttons            | `2rem`            |
+| `--b-carousel-btn-max`      | Maximum width and height for navigation buttons            | `3.125rem`        |
+| `--b-carousel-btns-display` | Display state of navigation buttons (set programmatically) | `block` or `none` |
+
+### Example: Customizing Button Size
+
+```css
+brick-carousel-v2 {
+  --b-carousel-btn-min: 2.5rem;
+  --b-carousel-btn-max: 4rem;
+}
+```
+
+## Common Patterns
+
+### Article Carousel with Teasers
+
+```html
+<brick-carousel-v2 data-min-slides-to-show="2">
+  <brick-teaser-v13 title="Breaking news story" type="story" vignette="News">
+  </brick-teaser-v13>
+  <brick-teaser-v13 title="Opinion piece" type="opinion" vignette="Opinion">
+  </brick-teaser-v13>
+  <brick-teaser-v13 title="Photo gallery" type="gallery" vignette="Photos">
+  </brick-teaser-v13>
+</brick-carousel-v2>
+```
+
+### Video Carousel
+
+```html
+<brick-carousel-v2>
+  <template>
+    <brick-player
+      mediaid="video1"
+      playerid="player123"
+      aspectratio="16:9"
+      title="Video 1"
+    >
+    </brick-player>
+  </template>
+  <template>
+    <brick-player
+      mediaid="video2"
+      playerid="player123"
+      aspectratio="16:9"
+      title="Video 2"
+    >
+    </brick-player>
+  </template>
+</brick-carousel-v2>
+```
+
+### Image Gallery with Hidden End Buttons
+
+```html
+<brick-carousel-v2 data-version="gallery" data-hide-btn-start-end="true">
+  <brick-image-v9 src="image1.jpg" alt="Gallery image 1"></brick-image-v9>
+  <brick-image-v9 src="image2.jpg" alt="Gallery image 2"></brick-image-v9>
+  <brick-image-v9 src="image3.jpg" alt="Gallery image 3"></brick-image-v9>
+</brick-carousel-v2>
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-carousel-v2`
+- **Base Class**: BrickElement
+- **Dependencies**: @amedia/brick-template (1.3.1), @amedia/brick-tokens (5.19.6)
+- **Renders as**: `<section>` containing navigation and content
+- **Browser Support**: Modern browsers with custom element support
+- **Mutation Observer**: Automatically detects and handles dynamically added children
+- **Scroll Behavior**: Uses CSS scroll-snap for smooth scrolling
+- **Drag Support**: Click-and-drag navigation on desktop (disabled on touch devices)
+
+## Important Notes
+
+### CSS Subgrid Issue
+
+There is a known issue with using CSS subgrid in carousel content. The `overflow: hidden` rule on `li.content-wrapper` can interfere with subgrid behavior. If you need to use subgrid, you must override the overflow rule in your own CSS and handle any overflow issues yourself.
+
+```css
+brick-carousel-v2 [data-content-wrapper] {
+  overflow: visible; /* Override for subgrid support */
+}
+```
+
+### Template Tag Usage (Client-side only)
+
+When using custom elements like `brick-player`, wrap them in `<template>` tags to prevent early initialization. The content must be a template string, not created with `createElement`, to avoid premature custom element initialization.
+
+### SSR vs Client-side Differences
+
+- **Client-side**: Direct children are automatically wrapped in `<li>` elements
+- **Server-side**: Use `dataItems` array with HTML strings that are wrapped by the template function
+- **Server-side parameters**: All parameters are strings (e.g., `dataMinSlidesToShow: '2'`)
+- **Validation**: Server-side function includes built-in validation with helpful error messages
+
+### Hide Buttons Caution
+
+The `data-hide-btn-start-end` attribute should generally not be used when carousel content is wrapped in links (like teasers), as disappearing buttons can cause users to accidentally click the underlying link.
+
+## Version
+
+Current version: 2.0.10

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

@@ -0,0 +1,147 @@
+---
+name: brick-classnames
+version: 2.1.0
+category: Utility
+tags: [utility, css, theming, design-system, classnames]
+use_cases: [theming, styling, design-tokens, css-variables]
+related: [brick-themes, brick-tokens]
+---
+
+# Brick Classnames
+
+A utility module that converts design theme names into CSS-safe class names for use with Brick design tokens.
+
+## Key Capabilities
+
+- Converts design theme names to CSS-safe class names
+- Ensures correct scoping for theme-specific CSS variables
+- Works seamlessly with brick-tokens theme CSS files
+- TypeScript support with type-safe design names
+- Simple, single-function API
+
+## API
+
+### `designNameToClassName(designName: Design): string`
+
+Converts a design theme name to a CSS-safe class name that corresponds with theme classes in brick-tokens.
+
+**Parameters:**
+
+- `designName`: `Design` - One of: `'nettavisen' | 'alt' | 'alfa' | 'bravo' | 'charlie'`
+
+**Returns:** `string` - A CSS class name (e.g., `'themeAlt'`, `'themeBravo'`)
+
+## Examples
+
+### Basic Usage
+
+```javascript
+import { designNameToClassName } from '@amedia/brick-classnames';
+
+const cssClass = designNameToClassName('alt');
+// Returns: 'themeAlt'
+
+const html = `<div class="${cssClass}">
+  <amedia-foo>bar</amedia-foo>
+</div>`;
+```
+
+### With CSS Variables
+
+```javascript
+const className = designNameToClassName('bravo');
+// Returns: 'themeBravo'
+
+// In your HTML
+const markup = `<div class="${className}">
+  <button>Styled with Bravo theme</button>
+</div>`;
+```
+
+```css
+/* Your component CSS can reference theme variables */
+.button {
+  color: var(--brick-colors-adText);
+  background: var(--brick-colors-primary);
+}
+```
+
+### All Available Themes
+
+```javascript
+import { designNameToClassName } from '@amedia/brick-classnames';
+
+designNameToClassName('nettavisen'); // 'themeNettavisen'
+designNameToClassName('alt'); // 'themeAlt'
+designNameToClassName('alfa'); // 'themeAlfa'
+designNameToClassName('bravo'); // 'themeBravo'
+designNameToClassName('charlie'); // 'themeCharlie'
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  import { designNameToClassName } from '@amedia/brick-classnames';
+
+  export let design = 'alt';
+
+  $: themeClass = designNameToClassName(design);
+</script>
+
+<div class={themeClass}>
+  <slot />
+</div>
+```
+
+### React
+
+```jsx
+import { designNameToClassName } from '@amedia/brick-classnames';
+
+function ThemedContainer({ design, children }) {
+  const themeClass = designNameToClassName(design);
+
+  return <div className={themeClass}>{children}</div>;
+}
+```
+
+## Technical Details
+
+- **Package**: `@amedia/brick-classnames`
+- **Type**: Utility function
+- **Dependencies**: `@amedia/brick-themes`
+- **Output format**: Camel-cased class name with 'theme' prefix
+
+## Important Notes
+
+- You must load the corresponding theme CSS file from Eik to use the CSS variables
+- Theme CSS files are available at: `https://assets.acdn.no/pkg/@amedia/brick-tokens/v2/css/theme-{name}.css`
+- The class name provides scoping for CSS variables defined in brick-tokens
+- TypeScript provides autocomplete and validation for design names
+
+## Common Patterns
+
+### Loading Theme CSS
+
+```javascript
+import { designNameToClassName } from '@amedia/brick-classnames';
+
+const design = 'bravo';
+const className = designNameToClassName(design);
+
+// Load the corresponding CSS file
+const link = document.createElement('link');
+link.rel = 'stylesheet';
+link.href = `https://assets.acdn.no/pkg/@amedia/brick-tokens/v2/css/theme-${design}.css`;
+document.head.appendChild(link);
+
+// Apply the class to enable scoped variables
+document.body.className = className;
+```
+
+## Version
+
+Current version: 2.1.0

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

@@ -0,0 +1,180 @@
+---
+name: brick-countdown
+version: 2.0.9
+selector: brick-countdown-v2
+category: Feedback
+tags: [countdown, timer, animation, teaser, time-based]
+use_cases:
+  [product-launches, event-countdown, limited-offers, time-sensitive-content]
+related: [brick-teaser]
+---
+
+# Brick Countdown
+
+An animated countdown component that displays time remaining until a specified date, with automatic updates and localization support.
+
+## Key Capabilities
+
+- Animated digit transitions with flip animation
+- Automatic countdown updates every second
+- Supports days, hours, minutes, and seconds display
+- Localization support (Norwegian Bokmål and Nynorsk)
+- Automatically hides when countdown reaches zero
+- Server-side rendering support via template function
+- Accessible with screen reader support
+
+## Props/Attributes
+
+| Attribute     | Type               | Default | Required | Description                                        |
+| ------------- | ------------------ | ------- | -------- | -------------------------------------------------- |
+| `data-date`   | EpochTimeStamp     | -       | yes      | Unix timestamp in milliseconds for the target date |
+| `data-text`   | string             | -       | no       | Optional text to display with the countdown        |
+| `data-locale` | 'nb_NO' \| 'nn_NO' | 'nb_NO' | no       | Locale for time unit labels                        |
+
+## Examples
+
+### Basic Countdown
+
+```html
+<brick-countdown-v2 data-date="1713515269513"></brick-countdown-v2>
+```
+
+### With Custom Text
+
+```html
+<brick-countdown-v2
+  data-date="1713515269513"
+  data-text="Starts in"
+></brick-countdown-v2>
+```
+
+### With Locale
+
+```html
+<brick-countdown-v2
+  data-date="1713515269513"
+  data-text="Tid igjen"
+  data-locale="nn_NO"
+></brick-countdown-v2>
+```
+
+### JavaScript Creation
+
+```javascript
+const el = document.createElement('brick-countdown-v2');
+el.dataset.date = '1713515269513';
+el.dataset.text = 'Event starts in';
+el.dataset.locale = 'nb_NO';
+document.body.appendChild(el);
+```
+
+## Server-Side Rendering
+
+### Import and Render
+
+```javascript
+import { renderBrickCountdown } from '@amedia/brick-countdown/template';
+
+const markup = renderBrickCountdown({
+  dataDate: 1713515269513,
+  dataText: 'Starts in',
+  dataLocale: 'nb_NO',
+});
+```
+
+### Client-Side Hydration
+
+After server-side rendering, load the client-side JavaScript for interactivity:
+
+```javascript
+import '@amedia/brick-countdown';
+```
+
+## Behavior
+
+### Countdown Logic
+
+- Updates every second with animated digit transitions
+- Hides days unit when less than 1 day remains
+- Automatically removes itself from DOM when countdown reaches zero
+- Validates date and logs error if invalid timestamp provided
+
+### Animation
+
+- Digits animate vertically using CSS custom properties
+- Smooth transitions between numbers
+- No animation for units that haven't changed
+
+## Accessibility
+
+- Uses semantic `<time>` element with `datetime` attribute
+- Screen reader text updates with countdown progress
+- Visual and screen reader content synchronized
+- Proper ARIA labeling for time remaining
+
+## Localization
+
+### Supported Locales
+
+**Norwegian Bokmål (nb_NO - default):**
+
+- days: "dager"
+- hours: "timer"
+- minutes: "minutter"
+- seconds: "sekunder"
+
+**Norwegian Nynorsk (nn_NO):**
+
+- days: "dagar"
+- hours: "timar"
+- minutes: "minutt"
+- seconds: "sekund"
+
+## Common Patterns
+
+### Event Countdown in Teaser
+
+```html
+<brick-teaser-v9>
+  <brick-countdown-v2
+    data-date="1713515269513"
+    data-text="Direktesending starter om"
+  ></brick-countdown-v2>
+  <!-- Other teaser content -->
+</brick-teaser-v9>
+```
+
+### Dynamic Countdown Creation
+
+```javascript
+function createCountdown(targetDate, text) {
+  const countdown = document.createElement('brick-countdown-v2');
+  countdown.dataset.date = targetDate.getTime().toString();
+  countdown.dataset.text = text;
+  return countdown;
+}
+
+const eventDate = new Date('2024-12-31T23:59:59');
+const countdownEl = createCountdown(eventDate, 'New Year in');
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-countdown-v2`
+- **Base Class**: BrickElement
+- **Dependencies**: `@amedia/brick-template`, `@amedia/brick-tokens`
+- **Renders as**: Custom element with `<time>` element inside
+- **Update Interval**: 1000ms (1 second)
+
+## Important Notes
+
+- Date must be provided as Unix timestamp in milliseconds
+- Component automatically removes itself when countdown ends
+- Days display is hidden when less than 24 hours remain
+- Invalid dates will log an error and prevent countdown from starting
+- Countdown stops updating when only days remain (no sub-day updates needed)
+- Uses `setInterval` which is automatically cleared on component disconnect
+
+## Version
+
+Current version: 2.0.9