@amedia/brick-mcp 1.0.3 → 1.0.4

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

@@ -1,108 +1,159 @@
 ---
 name: brick-template
-version: 2.0.0
+version: 2.1.0
 selector: N/A
 category: Utilities
-tags: [template, base-class, web-components, internal, foundation, boilerplate]
-use_cases: [component-development, web-component-creation, brick-component-foundation]
-related: [brick-tokens]
+tags: [template, base-class, web-components, internal, foundation, boilerplate, i18n, localization]
+use_cases: [component-development, web-component-creation, brick-component-foundation, internationalization]
+related: [brick-tokens, brick-helloworld]
 ---
 
 # Brick Template
 
-An internal foundational package that provides the base class and utilities for building Brick web components, handling common boilerplate and web component lifecycle management.
+An internal foundational package that provides the base class, decorator, and shared utilities for building Brick web components, including internationalization (i18n) support.
 
 ## Key Capabilities
 
-- Base `BrickElement` class for all Brick components
-- `defineCustomElement` decorator for component registration
-- Handles web component lifecycle (connectedCallback, disconnectedCallback, etc.)
-- Attribute observation and reactivity
-- Property-to-attribute synchronization
-- Shadow DOM management
-- Framework-agnostic web component standard implementation
-- TypeScript support with type definitions
+- Base `BrickElement` class that all Brick components extend from
+- `defineCustomElement` decorator for registering custom elements
+- Automatic attribute-to-property mirroring via `mirroredProps`
+- `childrenRenderedCallback` lifecycle hook for responding when child elements finish rendering
+- `camelCase` utility for converting attribute names to camelCase property names
+- i18n utilities (`getTranslation`, `requireLocale`) for component localization (added in 2.1.0)
 
 ## Core Exports
 
-### BrickElement Class
+### Main entry point (`@amedia/brick-template`)
 
-The base class that all Brick components extend from. Provides:
+| Export                 | Type       | Description                                                                 |
+| ---------------------- | ---------- | --------------------------------------------------------------------------- |
+| `BrickElement`         | class      | Base class extending `HTMLElement` for all Brick web components             |
+| `EventListenerObject`  | type       | Type for declarative event listener configuration (`{selector, action, listener}`) |
+| `defineCustomElement`  | function   | Decorator that registers a custom element with given config                 |
+| `camelCase`            | function   | Converts hyphenated attribute names (e.g. `data-text`) to camelCase (e.g. `dataText`) |
 
-- Automatic custom element registration
-- Lifecycle hooks
-- Attribute observation
-- Property management
-- Shadow DOM handling
+### i18n submodule (`@amedia/brick-template/i18n`)
 
-### defineCustomElement Decorator
+Added in version 2.1.0. Provides internationalization utilities for Brick components.
 
-A TypeScript decorator for declaring custom elements with automatic registration.
+| Export              | Type       | Description                                                                 |
+| ------------------- | ---------- | --------------------------------------------------------------------------- |
+| `getTranslation`    | function   | Looks up a translation key for a locale, falling back to `nb-NO`           |
+| `requireLocale`     | function   | Validates that a locale is provided and supported; throws if not            |
+| `SupportedLocales`  | type       | Union type: `'nb-NO' \| 'nn-NO' \| 'da-DK'`                               |
+| `I18n`              | type       | `Record<SupportedLocales, Record<string, string>>` for translation maps    |
 
-## Examples
+## BrickElement API
+
+### Constructor Behavior
+
+- Initializes `parameters` as an empty object
+- Sets `selector` from config or falls back to `tagName`
+- Creates a shadow DOM only if `config.shadow` is `true` (default is `false`)
+- If `mirroredProps` is defined on the subclass, auto-generates property getters/setters for each attribute (plus `data-locale`)
+
+### Properties
+
+| Property       | Type                       | Description                                                     |
+| -------------- | -------------------------- | --------------------------------------------------------------- |
+| `config`       | `Config`                   | Configuration set by `@defineCustomElement` decorator            |
+| `parameters`   | `Record<string, any>`      | Merged dataset from constructor params, `data-*` attributes, and `data` property |
+| `root`         | `this \| ShadowRoot`       | Render target (`this` when no shadow DOM, `ShadowRoot` otherwise) |
+| `isRendered`   | `boolean`                  | Reflects the `is-rendered` attribute; when true, skips DOM injection on connect |
+| `HTML`         | `string`                   | Override this getter in subclasses to define component markup    |
+
+### Lifecycle Methods
 
-### Basic Component
+| Method                        | Description                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `connectedCallback()`         | Merges parameters, attaches DOM (if not already rendered), adds event listeners, and appends `<brick-children-rendered>` trigger element |
+| `disconnectedCallback()`      | Removes all event listeners                                                      |
+| `childrenRenderedCallback()`  | Called after child elements have rendered; override in subclasses to react        |
+| `attachDOM()`                 | Clones the HTML template into the component root; applies host styles            |
+
+### Declarative Event Listeners
+
+Override the `eventListeners` getter to return an array of `EventListenerObject`:
 
 ```typescript
-import { BrickElement, defineCustomElement } from '@amedia/brick-template';
-import { css } from '@amedia/brick-tokens';
+get eventListeners(): EventListenerObject[] {
+  return [
+    { selector: 'this', action: 'click', listener: this.handleClick },
+    { selector: '.my-button', action: 'click', listener: this.onButton },
+    { selector: 'window', action: 'resize', listener: this.onResize },
+  ];
+}
+```
 
-const titleClass = css({
-  color: '$supportiveBlackText',
-  backgroundColor: '$supportiveBlackBg'
-});
+Special `selector` values: `'this'` targets the component root, `'window'` targets the global window object.
 
-@defineCustomElement({
-  selector: 'brick-is-awesome',
-})
-class BrickIsAwesome extends BrickElement {
-  get HTML() {
-    return `<h1 class="${titleClass}">Brick is Awesome!</h1>`;
-  }
+### Mirrored Props
+
+Define a static `mirroredProps` array on your subclass to auto-sync `data-*` attributes with camelCase properties:
+
+```typescript
+static get mirroredProps() {
+  return ['data-text', 'data-size'];
 }
+// This creates this.dataText and this.dataSize properties
+// that read from / write to the corresponding attributes.
+// data-locale is always included automatically.
 ```
 
-### Component with Properties
+## `defineCustomElement` Decorator
+
+### Config Interface
+
+| Property    | Type     | Required | Default | Description                                    |
+| ----------- | -------- | -------- | ------- | ---------------------------------------------- |
+| `selector`  | `string` | yes      | -       | Custom element tag name (must contain a hyphen) |
+| `shadow`    | `boolean`| no       | `false` | Whether to use Shadow DOM                      |
+| `component` | `any`    | no       | -       | Optional framework component reference         |
+| `version`   | `string` | no       | `'1.0.0'` | Component version string                     |
+| `name`      | `string` | no       | -       | Sets `brick-component` attribute on element    |
+
+## Usage
+
+### Creating a Brick Component
 
 ```typescript
 import { BrickElement, defineCustomElement } from '@amedia/brick-template';
 
 @defineCustomElement({
-  selector: 'brick-example',
+  selector: 'brick-example-v2',
 })
 class BrickExample extends BrickElement {
-  // Define observed attributes
-  static get observedAttributes() {
+  static get mirroredProps() {
     return ['data-label', 'data-value'];
   }
 
-  // Getters for properties
-  get dataLabel() {
-    return this.getAttribute('data-label') || '';
+  static get observedAttributes() {
+    return ['children-rendered'];
   }
 
-  set dataLabel(value: string) {
-    this.setAttribute('data-label', value);
+  get HTML() {
+    return `<div><span>${this.dataLabel}</span>: <span>${this.dataValue}</span></div>`;
   }
+}
+```
 
-  get dataValue() {
-    return this.getAttribute('data-value') || '';
-  }
+### Using i18n Utilities
 
-  set dataValue(value: string) {
-    this.setAttribute('data-value', value);
-  }
+```typescript
+import { getTranslation, requireLocale } from '@amedia/brick-template/i18n';
+import type { I18n, SupportedLocales } from '@amedia/brick-template/i18n';
 
-  // Render method
-  get HTML() {
-    return `
-      <div>
-        <span>${this.dataLabel}</span>
-        <span>${this.dataValue}</span>
-      </div>
-    `;
-  }
-}
+const translations: I18n = {
+  'nb-NO': { greeting: 'Hei' },
+  'nn-NO': { greeting: 'Hei' },
+  'da-DK': { greeting: 'Hej' },
+};
+
+// Validate locale (throws if missing or unsupported)
+requireLocale(locale, 'brick-my-component', ['nb-NO', 'nn-NO', 'da-DK']);
+
+// Look up translation, falls back to nb-NO if key missing for locale
+const text = getTranslation(translations, 'nn-NO', 'greeting'); // "Hei"
 ```
 
 ### Component with Lifecycle Hooks
@@ -111,116 +162,64 @@ class BrickExample extends BrickElement {
 import { BrickElement, defineCustomElement } from '@amedia/brick-template';
 
 @defineCustomElement({
-  selector: 'brick-lifecycle',
+  selector: 'brick-lifecycle-v1',
 })
 class BrickLifecycle extends BrickElement {
   connectedCallback() {
     super.connectedCallback();
-    console.log('Component connected to DOM');
+    // Component is now in the DOM
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
-    console.log('Component removed from DOM');
-  }
-
-  attributeChangedCallback(name: string, oldValue: string, newValue: string) {
-    super.attributeChangedCallback(name, oldValue, newValue);
-    console.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
-  }
-
-  get HTML() {
-    return `<div>Lifecycle Component</div>`;
+    // Component removed from DOM
   }
-}
-```
-
-## Usage in Brick Components
-
-All Brick components use brick-template as their foundation:
-
-```typescript
-import { BrickElement, defineCustomElement } from '@amedia/brick-template';
-import { css } from '@amedia/brick-tokens';
 
-@defineCustomElement({
-  selector: 'brick-button-v9',
-})
-export class BrickButton extends BrickElement {
-  static get observedAttributes() {
-    return ['data-label', 'data-version', 'data-size'];
+  childrenRenderedCallback() {
+    // All children have finished rendering
+    this.processChildren();
   }
 
   get HTML() {
-    return `<button>${this.dataLabel}</button>`;
+    return `<div>Content</div>`;
   }
 }
 ```
 
-## BrickElement API
-
-### Properties
-
-- `shadowRoot`: Access to the component's shadow DOM
-- `observedAttributes`: Static property defining which attributes to watch
+## i18n Details
 
-### Lifecycle Methods
-
-- `connectedCallback()`: Called when element is inserted into DOM
-- `disconnectedCallback()`: Called when element is removed from DOM
-- `attributeChangedCallback(name, oldValue, newValue)`: Called when observed attribute changes
-- `adoptedCallback()`: Called when element is moved to a new document
-
-### Template Method
-
-- `get HTML()`: Override this getter to define your component's template
+### `getTranslation(i18n, locale, key)`
 
-## Framework Compatibility
+- Looks up `i18n[locale][key]`
+- Falls back to `i18n['nb-NO'][key]` if not found for the given locale
+- Returns the raw `key` string if no translation exists at all
 
-Brick-template creates standard web components that work with:
+### `requireLocale(locale, component, supported)`
 
-- Vanilla JavaScript
-- Svelte
-- React
-- Vue
-- Angular
-- Any framework that supports web components
+- Throws an error if `locale` is `undefined` or not included in the `supported` array
+- Error messages include the component name and list of supported locales
+- Use this for components where locale is mandatory
 
-```javascript
-// Vanilla JS
-import '@amedia/brick-button';
-const button = document.createElement('brick-button-v9');
-button.dataLabel = 'Click me';
+### Supported Locales
 
-// Svelte
-import '@amedia/brick-button';
-<brick-button-v9 data-label="Click me" />
-
-// React
-import '@amedia/brick-button';
-<brick-button-v9 data-label="Click me" />
-```
+The `SupportedLocales` type defines: `'nb-NO'` (Norwegian Bokmal), `'nn-NO'` (Norwegian Nynorsk), `'da-DK'` (Danish).
 
 ## Technical Details
 
-- **Package Type**: Internal utility/foundation package
-- **Output**: BrickElement class and defineCustomElement decorator
-- **Standard**: Web Components standard (Custom Elements v1)
-- **TypeScript**: Full TypeScript support with type definitions
-- **Shadow DOM**: Automatic shadow DOM creation and management
-- **Dependencies**: None (standalone foundation)
+- **Package version**: `2.1.0`
+- **Custom Element tag**: N/A (this is a base class package, not a standalone component; individual Brick components define their own selectors)
+- **Output format**: ESM only (CommonJS removed in 2.0.0)
+- **Shadow DOM**: Disabled by default (`shadow: false`); opt-in via `defineCustomElement` config
+- **Dependencies**: None (standalone foundation package)
+- **Submodules**: Main entry (`@amedia/brick-template`), i18n entry (`@amedia/brick-template/i18n`)
 
 ## Important Notes
 
-- This is an internal package used by all Brick components
-- Not meant to be used directly in applications
-- Provides the foundation for the Brick component architecture
-- All Brick components extend BrickElement
-- Handles common web component boilerplate automatically
-- Version 2.0.0 is the current stable version
-- Components must override the `HTML` getter to define their template
-- The `@defineCustomElement` decorator automatically registers the custom element
-
-## Version
-
-Current version: 2.0.0
+- This is an internal package used as the foundation for all Brick components; it is not meant to be used directly in applications.
+- All Brick components must extend `BrickElement` and use the `@defineCustomElement` decorator.
+- Override the `HTML` getter to define component markup; BrickElement clones from a `<template>` element for performance.
+- When a component is server-side rendered (has `is-rendered` attribute), BrickElement skips DOM injection in `connectedCallback` to avoid duplicating content.
+- The `mirroredProps` mechanism always includes `data-locale` automatically, even if not listed, to support i18n.
+- Version 2.0.0 removed CommonJS support; only ES modules are exported.
+- Version 2.1.0 added the `i18n` submodule with `getTranslation`, `requireLocale`, `SupportedLocales`, and `I18n` exports.
+- The `childrenRenderedCallback` lifecycle hook (added in 1.3.0) fires after all child elements have rendered; it works by appending a `<brick-children-rendered>` helper element that triggers the callback and then removes itself.

package/dist/data/components-metadata.json

@@ -1,7 +1,7 @@
 [
   {
     "name": "brick-alt-teaser",
-    "version": "8.1.24",
+    "version": "8.1.27",
     "selector": "brick-alt-teaser-v8",
     "category": "Display",
     "tags": [
@@ -11,7 +11,7 @@
   },
   {
     "name": "brick-avatar",
-    "version": "0.2.61",
+    "version": "0.2.64",
     "selector": "brick-avatar-v0",
     "description": "brick-avatar component",
     "category": "Display",
@@ -23,7 +23,7 @@
   },
   {
     "name": "brick-button",
-    "version": "9.4.19",
+    "version": "9.4.22",
     "selector": "brick-button-v9",
     "category": "Forms",
     "tags": [
@@ -35,15 +35,15 @@
   },
   {
     "name": "brick-byline",
-    "version": "1.0.23",
-    "selector": "brick-byline-v1",
+    "version": "2.0.0",
+    "selector": "brick-byline-v2",
     "description": "brick-byline component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-byline",
     "mainJsFile": "brick-byline.js"
   },
   {
     "name": "brick-card",
-    "version": "7.3.33",
+    "version": "7.3.36",
     "selector": "brick-card-v7",
     "category": "Layout",
     "tags": [
@@ -54,7 +54,7 @@
   },
   {
     "name": "brick-carousel",
-    "version": "2.3.6",
+    "version": "2.3.9",
     "selector": "brick-carousel-v2",
     "description": "Simple carousel for any content passed to it.",
     "category": "Display",
@@ -78,7 +78,7 @@
   },
   {
     "name": "brick-countdown",
-    "version": "3.0.8",
+    "version": "3.0.11",
     "selector": "brick-countdown-v3",
     "description": "brick-countdown component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-countdown",
@@ -86,7 +86,7 @@
   },
   {
     "name": "brick-dialog",
-    "version": "2.1.16",
+    "version": "2.1.19",
     "selector": "brick-dialog-v2",
     "description": "brick-dialog component",
     "category": "Feedback",
@@ -98,7 +98,7 @@
   },
   {
     "name": "brick-expand",
-    "version": "0.0.28",
+    "version": "0.0.31",
     "selector": "brick-expand-v0",
     "description": "brick-expand component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-expand",
@@ -117,7 +117,7 @@
   },
   {
     "name": "brick-helloworld",
-    "version": "2.0.29",
+    "version": "2.1.2",
     "selector": "brick-helloworld-v2",
     "description": "Brick Hello World component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-helloworld",
@@ -125,7 +125,7 @@
   },
   {
     "name": "brick-icon",
-    "version": "2.4.0",
+    "version": "2.4.3",
     "selector": "brick-icon-v2",
     "category": "Display",
     "tags": [
@@ -143,7 +143,7 @@
   },
   {
     "name": "brick-image",
-    "version": "6.0.28",
+    "version": "6.0.31",
     "selector": "brick-image-v6",
     "category": "Display",
     "tags": [
@@ -154,7 +154,7 @@
   },
   {
     "name": "brick-input",
-    "version": "4.0.8",
+    "version": "4.0.11",
     "selector": "brick-input-v4",
     "description": "brick-input component",
     "category": "Forms",
@@ -167,14 +167,14 @@
   },
   {
     "name": "brick-pill",
-    "version": "10.1.7",
+    "version": "10.1.10",
     "selector": "brick-pill-v10",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-pill",
     "mainJsFile": "brick-pill.js"
   },
   {
     "name": "brick-player",
-    "version": "2.4.4",
+    "version": "2.4.7",
     "selector": "brick-player-v2",
     "description": "Component for playing video and audio files",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-player",
@@ -182,7 +182,7 @@
   },
   {
     "name": "brick-published",
-    "version": "4.0.24",
+    "version": "4.0.27",
     "selector": "brick-published-v4",
     "description": "brick-published",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-published",
@@ -190,7 +190,7 @@
   },
   {
     "name": "brick-share",
-    "version": "0.4.4",
+    "version": "0.4.7",
     "selector": "brick-share-v0",
     "description": "brick-share component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-share",
@@ -198,7 +198,7 @@
   },
   {
     "name": "brick-skip-link",
-    "version": "0.0.3",
+    "version": "0.0.6",
     "selector": "brick-skip-link-v0",
     "description": "brick-skip-link component",
     "category": "Navigation",
@@ -210,7 +210,7 @@
   },
   {
     "name": "brick-stepper",
-    "version": "1.1.10",
+    "version": "1.1.13",
     "selector": "brick-stepper-v1",
     "description": "brick-stepper component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-stepper",
@@ -218,7 +218,7 @@
   },
   {
     "name": "brick-tab",
-    "version": "0.1.31",
+    "version": "0.1.34",
     "selector": "brick-tab-v0",
     "description": "brick-tab component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-tab",
@@ -226,7 +226,7 @@
   },
   {
     "name": "brick-tabs",
-    "version": "0.1.32",
+    "version": "0.1.35",
     "selector": "brick-tabs-v0",
     "description": "brick-tabs component handling tablist, tabs and tabpanel",
     "category": "Navigation",
@@ -238,7 +238,7 @@
   },
   {
     "name": "brick-tag",
-    "version": "0.0.31",
+    "version": "0.0.34",
     "selector": "brick-tag-v0",
     "description": "brick-tag component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-tag",
@@ -246,7 +246,7 @@
   },
   {
     "name": "brick-teaser",
-    "version": "22.2.10",
+    "version": "22.2.13",
     "selector": "brick-teaser-v22",
     "description": "Teaser component.",
     "category": "Display",
@@ -258,7 +258,7 @@
   },
   {
     "name": "brick-teaser-player",
-    "version": "1.1.21",
+    "version": "1.1.24",
     "selector": "brick-teaser-player-v1",
     "description": "brick-video-teaser component",
     "category": "Display",
@@ -270,7 +270,7 @@
   },
   {
     "name": "brick-teaser-reels",
-    "version": "0.4.23",
+    "version": "0.4.26",
     "selector": "brick-teaser-reels-v0",
     "description": "brick-teaser-reels component",
     "category": "Display",
@@ -282,7 +282,7 @@
   },
   {
     "name": "brick-textarea",
-    "version": "2.0.27",
+    "version": "2.0.30",
     "selector": "brick-textarea-v2",
     "description": "brick-textarea component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-textarea",
@@ -298,7 +298,7 @@
   },
   {
     "name": "brick-toast",
-    "version": "0.1.45",
+    "version": "0.1.48",
     "selector": "brick-toast-v0",
     "description": "brick-toast component",
     "category": "Feedback",
@@ -310,7 +310,7 @@
   },
   {
     "name": "brick-toggle",
-    "version": "3.1.33",
+    "version": "3.1.36",
     "selector": "brick-toggle-v3",
     "description": "brick-toggle component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-toggle",
@@ -318,7 +318,7 @@
   },
   {
     "name": "brick-tokens",
-    "version": "6.2.2",
+    "version": "6.3.0",
     "selector": "brick-tokens-v6",
     "description": "Tokens package",
     "category": "Utilities",
@@ -330,7 +330,7 @@
   },
   {
     "name": "brick-tooltip",
-    "version": "1.0.34",
+    "version": "1.0.37",
     "selector": "brick-tooltip-v1",
     "description": "brick-tooltip component",
     "assetUrl": "https://assets.acdn.no/pkg/@amedia/brick-tooltip",