@amedia/brick-mcp 1.0.3 → 1.0.5

package/data/components/brick-helloworld.md

@@ -1,6 +1,6 @@
 ---
 name: brick-helloworld
-version: 2.0.2
+version: 2.1.0
 selector: brick-helloworld-v2
 category: Development
 tags:
@@ -12,6 +12,8 @@ tags:
     web-components,
     template,
     getting-started,
+    i18n,
+    localisation,
   ]
 use_cases:
   [
@@ -20,209 +22,176 @@ use_cases:
     understanding-component-anatomy,
     server-side-rendering-examples,
     client-side-rendering-examples,
+    localisation-examples,
   ]
 related: [brick-input, brick-toggle, brick-template]
 ---
 
 # Brick Helloworld
 
-A demonstration component showcasing the anatomy and usage patterns of Brick components, used for testing and educational purposes.
+A demonstration component showcasing the anatomy and usage patterns of Brick components, including server-side rendering, client-side rendering, template slots, component composition, and localisation (i18n).
 
 ## Key Capabilities
 
 - Demonstrates both server-side and client-side rendering patterns
-- Shows template processing with named template slots
+- Supports localisation via `data-locale` attribute with `nb-NO`, `nn-NO`, and `da-DK` locales
 - Integrates with other Brick components (brick-input, brick-toggle)
-- Illustrates mirrored props and observed attributes
-- Provides examples of Stitches styling integration
+- Shows template processing with named template slots
+- Illustrates Stitches styling with typography variants via `data-version`
 - Serves as a reference implementation for new Brick components
 
 ## Props/Attributes
 
-| Attribute           | Type    | Default   | Required | Description                                                   |
-| ------------------- | ------- | --------- | -------- | ------------------------------------------------------------- |
-| `data-text`         | string  | undefined | no       | Text content to display in the component                      |
-| `data-version`      | string  | undefined | no       | Version string used for styling variants                      |
-| `is-rendered`       | boolean | false     | no       | Indicates if markup was rendered server-side                  |
-| `children-rendered` | string  | undefined | no       | Internal attribute set when child components finish rendering |
-
-## Examples
-
-### Basic Usage - Template Literals
-
-```html
-<brick-helloworld-v2 data-text="Hello, World!" data-version="v2">
-  <template name="content">
-    <p>I am a paragraph inside a template named content</p>
-  </template>
-</brick-helloworld-v2>
-```
+| Attribute           | Type                                   | Default     | Required | Description                                                                         |
+| ------------------- | -------------------------------------- | ----------- | -------- | ----------------------------------------------------------------------------------- |
+| `data-text`         | `string`                               | `undefined` | no       | Text content to display in the component                                            |
+| `data-version`      | `"baseHeadlineXs" \| "baseMetaM" \| "baseMetaS" \| "baseHeadlineL" \| "baseHeadlineM" \| "baseBodyM"` | `"baseBodyM"` | no | Typography variant used for styling; maps to a Stitches variant in `styles.js` |
+| `data-locale`       | `"nb-NO" \| "nn-NO" \| "da-DK"`       | `undefined` | no       | Locale for translated text. Must be a supported locale or the component will throw  |
+| `is-rendered`       | `boolean`                              | `false`     | no       | Indicates if markup was rendered server-side; prevents client-side DOM recreation    |
+| `children-rendered` | `string`                               | `undefined` | no       | Internal attribute set when child components finish rendering; triggers template processing |
 
-### JavaScript createElement
+## Usage
 
-```javascript
-const el = document.createElement('brick-helloworld-v2');
-el.dataset.text = 'The quick brown fox jumps over the lazy dog';
-el.dataset.version = 'v2';
-document.body.appendChild(el);
-```
+### Server-side rendering (preferred)
 
-### Server-Side Rendering
+Import the render function from the `/template` submodule and call it to produce an HTML string:
 
-```javascript
+```ts
 import {
   renderBrickHelloworld,
   getCssText,
 } from '@amedia/brick-helloworld/template';
 
-const markup = renderBrickHelloworld({
-  dataText: 'The quick brown fox jumps over the lazy dog',
-  dataVersion: 'v2',
-  isRendered: true,
+const html = renderBrickHelloworld({
+  dataText: 'Hello, World!',
+  dataVersion: 'baseBodyM',
+  dataLocale: 'nb-NO',
 });
 
-// Include the styles
+// Include the critical CSS for the component
 const css = `<style>${getCssText()}</style>`;
 ```
 
-### Client-Side Import
+When `isRendered` is omitted it defaults to `true` in the render function, which wraps the output in a `<brick-helloworld ...>` custom element tag with the `is-rendered` attribute. This prevents the client-side Web Component from recreating the DOM.
 
-```javascript
-// Via npm
-import '@amedia/brick-helloworld';
+#### SSR with a different locale
+
+```ts
+const html = renderBrickHelloworld({
+  dataText: 'Hej verden!',
+  dataVersion: 'baseHeadlineM',
+  dataLocale: 'da-DK',
+});
+```
+
+#### SSR for client-side hydration only (no server markup)
 
-// Via Eik CDN
-import 'https://assets.acdn.no/pkg/@amedia/brick-helloworld/v2/brick-helloworld.js';
+```ts
+const html = renderBrickHelloworld({
+  dataText: 'Will be rendered client-side',
+  dataVersion: 'baseBodyM',
+  dataLocale: 'nb-NO',
+  isRendered: false,
+});
 ```
 
-### Using Template Slots
+### Client-side (declarative HTML)
+
+Use the custom element directly in HTML after registering the component:
 
 ```html
-<brick-helloworld-v2 data-text="Main content" data-version="v2">
+<script
+  type="module"
+  src="https://assets.acdn.no/pkg/@amedia/brick-helloworld/v2/brick-helloworld.js"
+></script>
+
+<brick-helloworld-v2
+  data-text="Hello, World!"
+  data-version="baseBodyM"
+  data-locale="nb-NO"
+>
+</brick-helloworld-v2>
+```
+
+#### With template slots
+
+```html
+<brick-helloworld-v2
+  data-text="Main content"
+  data-version="baseBodyM"
+  data-locale="nb-NO"
+>
   <template name="content">
-    <div class="custom-content">
-      <h2>Custom Template Content</h2>
-      <p>This content is processed by the component</p>
-    </div>
+    <p>I am a paragraph inside a template named content</p>
   </template>
 </brick-helloworld-v2>
 ```
 
-## Framework Integration
+After the component's children have rendered (tracked via the `children-rendered` attribute), the component processes `<template name="content">` elements: it extracts the template content, wraps it in a `<div>`, appends it to the component, and removes the original `<template>` element.
 
-### Node.js (>=18) - HTTPS Imports
-
-```javascript
-// Using HTTPS imports (Node.js >= 18)
-import {
-  renderBrickHelloworld,
-  getCssText,
-} from 'https://assets.acdn.no/pkg/@amedia/brick-helloworld/v2/template.js';
+#### JavaScript createElement
 
-const html = renderBrickHelloworld({
-  dataText: 'Server rendered content',
-  dataVersion: 'v2',
-});
+```js
+const el = document.createElement('brick-helloworld-v2');
+el.dataset.text = 'The quick brown fox jumps over the lazy dog';
+el.dataset.version = 'baseBodyM';
+el.dataset.locale = 'nb-NO';
+document.body.appendChild(el);
 ```
 
-## Programmatic Usage
-
-```javascript
-import { BrickHelloworld } from '@amedia/brick-helloworld';
+#### npm import
 
-const component = new BrickHelloworld();
-component.dataText = 'Programmatically set text';
-component.dataVersion = 'v2';
-document.body.appendChild(component);
+```js
+import '@amedia/brick-helloworld';
 ```
 
-## Common Patterns
+## Localisation
 
-### Hybrid Server/Client Rendering
+Added in version 2.1.0. The component supports localisation via `data-locale` and the `@amedia/brick-template` i18n utilities.
 
-When markup is rendered server-side with `isRendered: true`, the component will not recreate the DOM client-side but will still attach event listeners and process templates:
+Supported locales and their translations for the `helloworld:text` key:
 
-```html
-<!-- Server-rendered HTML -->
-<brick-helloworld-v2 data-version="v2" data-text="Content" is-rendered>
-  <div class="hello-v2">
-    Content
-    <div class="hello-v2">v2</div>
-  </div>
-  <!-- Child components rendered server-side -->
-</brick-helloworld-v2>
+| Locale  | Translation                |
+| ------- | -------------------------- |
+| `nb-NO` | Spraket er norsk bokmal    |
+| `nn-NO` | Spraket er norsk nynorsk   |
+| `da-DK` | Sproget er dansk           |
 
-<!-- Client-side script -->
-<script
-  type="module"
-  src="https://assets.acdn.no/pkg/@amedia/brick-helloworld/v2/brick-helloworld.js"
-></script>
-```
+The component calls `requireLocale()` which throws an error if an unsupported locale is provided. This is a deliberate fail-fast approach: the component will not silently fall back to a default locale.
 
-### Template Processing
-
-The component demonstrates how to process named template slots and move content:
-
-```javascript
-// Component processes template[name="content"]
-// and moves it into a div wrapper
-processTemplates() {
-  const templateContent = this.querySelector('template[name="content"]');
-  if (templateContent) {
-    const range = document.createRange();
-    range.selectNodeContents(templateContent.content);
-    const contentWrapper = document.createElement('div');
-    range.surroundContents(contentWrapper);
-    this.appendChild(contentWrapper);
-    templateContent.remove();
-  }
-}
-```
+Translations are defined in `src/i18n.ts` and must conform to the `I18n` type from `@amedia/brick-template`.
 
-### Component Composition
+## Accessibility
 
-Shows integration with other Brick components:
-
-```html
-<brick-helloworld-v2 data-text="Form Example" data-version="v2">
-  <!-- brick-input and brick-toggle are automatically included -->
-</brick-helloworld-v2>
-```
+- This is a development/demo component and does not implement specific ARIA patterns
+- Child components (brick-input, brick-toggle) handle their own accessibility concerns
+- Not intended for production use; accessibility testing is disabled in Storybook (`a11y: { disable: true }`)
 
 ## Technical Details
 
-- **Custom Element**: `brick-helloworld-v2`
-- **Base Class**: BrickElement (from @amedia/brick-template)
-- **Dependencies**: @amedia/brick-tokens, @amedia/brick-template, @amedia/brick-input, @amedia/brick-toggle
-- **Renders as**: Custom element with internal div structure
-- **Styling**: Stitches-based styling with variant support
-- **Mirrored Props**: `data-text`, `data-version` (automatically synced between attributes and properties)
+- **Package version**: `2.1.0`
+- **Custom Element tag**: `brick-helloworld-v2` -- must match the `selector` in frontmatter; the tag uses only the **major** version, not the full semver
+- **Base Class**: `BrickElement` (from `@amedia/brick-template`)
+- **Dependencies**: `@amedia/brick-tokens@6.2.2`, `@amedia/brick-template@2.1.0`, `@amedia/brick-input@4.0.9`, `@amedia/brick-toggle@3.1.34`
+- **Mirrored Props**: `data-text`, `data-version` (automatically synced between HTML attributes and JS properties)
 - **Observed Attributes**: `children-rendered`
+- **Styling**: Stitches-based via `@amedia/brick-tokens`; typography variants controlled by `data-version`
+- **SSR export**: `@amedia/brick-helloworld/template` exports `renderBrickHelloworld` and `getCssText`
 
 ## Important Notes
 
-- This is a demonstration/example component primarily for development and testing purposes
-- Not intended for production use cases - serves as a reference implementation
-- Demonstrates the complete anatomy of a Brick component including build configuration
-- Used for testing release workflows, publishing, and build processes
-- Template processing occurs after children are rendered (via `children-rendered` attribute)
-- The component automatically includes brick-input and brick-toggle as child dependencies
-- Server-side rendering requires the `/template` export path
-- CSS is automatically injected when used client-side, but must be manually included for SSR via `getCssText()`
-
-## Installation
-
-```bash
-npm install @amedia/brick-helloworld
-```
-
-## Version
+- This is a demonstration/example component for development and testing purposes; it is not intended for production use
+- The `data-version` attribute controls typography styling variants, not the package version; valid values are Stitches variant keys like `baseBodyM`, `baseHeadlineL`, etc.
+- `requireLocale()` will throw if `data-locale` is missing or unsupported -- this is intentional fail-fast behaviour
+- Template processing (named `<template>` slots) occurs only after all children have rendered, triggered by the `children-rendered` attribute
+- The component automatically includes brick-input and brick-toggle as child dependencies in both SSR and client-side modes
+- Server-side rendering requires the `/template` export path; CSS must be manually included via `getCssText()`
+- The package is ESM only -- there is no CommonJS export
 
-Current version: 2.0.2
+## Changelog (recent)
 
-## Package Exports
+### 2.1.0
 
-- **ESM (Node)**: `dist/index.mjs`
-- **CommonJS (Node)**: `dist/index.js`
-- **Browser Bundle (Eik)**: `dist/eik/brick-helloworld.js`
-- **Template (SSR)**: `template/index.mjs`
+- Added localisation support via `data-locale` attribute (proof of concept)
+- Created component-specific translations in `src/i18n.ts`
+- Updated dependency on `@amedia/brick-template@2.1.0` which provides `getTranslation`, `requireLocale`, `SupportedLocales` type, and `I18n` type