@amedia/brick-mcp 0.0.2 → 0.1.1

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

@@ -0,0 +1,373 @@
+---
+name: brick-button
+version: 9.3.1
+selector: brick-button-v9
+category: Forms
+tags: [button, cta, action, interactive, link, form-control]
+use_cases:
+  [
+    forms,
+    call-to-action,
+    navigation,
+    user-interaction,
+    authentication,
+    checkout,
+    product-listing,
+    modal-triggers,
+  ]
+related: [brick-icon, brick-tokens]
+---
+
+# Brick Button
+
+A customizable, accessible button component that supports multiple visual variants, sizes, and can render as either a button or link element.
+
+## Key Capabilities
+
+- Three visual variants: primary, secondary, and outlined
+- Renders as `<button>` or `<a>` based on presence of `data-linkto` attribute
+- Two size options: small and medium
+- Icon support with configurable placement (left, right, top)
+- Full ARIA attribute support for accessibility
+- CSS custom properties for styling customization
+- Analytics integration via ADP attributes
+- Framework-agnostic web component with SSR support
+
+## Props/Attributes
+
+| Attribute               | Type                                     | Default     | Required | Description                                                         |
+| ----------------------- | ---------------------------------------- | ----------- | -------- | ------------------------------------------------------------------- |
+| `data-label`            | string                                   | -           | yes      | Button text/label                                                   |
+| `data-version`          | `'primary' \| 'secondary' \| 'outlined'` | `'primary'` | no       | Visual style variant                                                |
+| `data-size`             | `'small' \| 'medium'`                    | `'medium'`  | no       | Button size                                                         |
+| `data-linkto`           | string                                   | -           | no       | URL to navigate to. When set, renders as `<a>` tag                  |
+| `data-target`           | string                                   | -           | no       | Link target (e.g., `_blank` for new tab)                            |
+| `data-icon-id`          | string                                   | -           | no       | ID of icon from brick-icon to display                               |
+| `data-iconplacement`    | `'top' \| 'right' \| 'left'`             | `'left'`    | no       | Position of icon relative to label                                  |
+| `data-icontext`         | string                                   | -           | no       | Alternative text for icon                                           |
+| `data-disabled`         | string                                   | -           | no       | Disables the button when set to "true"                              |
+| `data-as`               | `'span' \| 'div'`                        | -           | no       | Renders as non-interactive element (for use with framework routers) |
+| `data-adplabel`         | string                                   | -           | no       | ADP analytics click label                                           |
+| `data-adpvalue`         | string                                   | -           | no       | ADP analytics click value                                           |
+| `data-aria-label`       | string                                   | -           | no       | ARIA label for accessibility                                        |
+| `data-aria-labelledby`  | string                                   | -           | no       | ID of element that labels this button                               |
+| `data-aria-describedby` | string                                   | -           | no       | ID of element that describes this button                            |
+| `data-aria-controls`    | string                                   | -           | no       | ID of element controlled by this button                             |
+| `data-aria-expanded`    | string                                   | -           | no       | Indicates if controlled element is expanded                         |
+| `data-aria-pressed`     | string                                   | -           | no       | Indicates pressed state for toggle buttons                          |
+
+## Examples
+
+### Basic Button
+
+```html
+<brick-button-v9 data-label="Click me" data-version="primary">
+</brick-button-v9>
+```
+
+### Button Variants
+
+```html
+<!-- Primary button -->
+<brick-button-v9 data-label="Primary Action" data-version="primary">
+</brick-button-v9>
+
+<!-- Secondary button -->
+<brick-button-v9 data-label="Secondary Action" data-version="secondary">
+</brick-button-v9>
+
+<!-- Outlined button -->
+<brick-button-v9 data-label="Outlined Action" data-version="outlined">
+</brick-button-v9>
+```
+
+### Button as Link
+
+```html
+<brick-button-v9
+  data-label="Visit Amedia"
+  data-version="primary"
+  data-linkto="https://www.amedia.no"
+  data-target="_blank"
+>
+</brick-button-v9>
+```
+
+### Button with Icon
+
+```html
+<brick-button-v9
+  data-label="Search"
+  data-version="primary"
+  data-icon-id="search"
+  data-iconplacement="left"
+>
+</brick-button-v9>
+
+<!-- Icon-only button -->
+<brick-button-v9 data-icon-id="menu" data-aria-label="Open menu">
+</brick-button-v9>
+```
+
+### Small Button
+
+```html
+<brick-button-v9
+  data-label="Small Action"
+  data-version="secondary"
+  data-size="small"
+>
+</brick-button-v9>
+```
+
+### Disabled Button
+
+```html
+<brick-button-v9
+  data-label="Disabled"
+  data-version="primary"
+  data-disabled="true"
+>
+</brick-button-v9>
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  import '@amedia/brick-button';
+
+  function handleClick() {
+    console.log('Button clicked!');
+  }
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<brick-button-v9
+  data-label="Click me"
+  data-version="primary"
+  onclick={handleClick}
+/>
+```
+
+### Using with Framework Routers
+
+When using with framework routers (like svelte-routing), use `data-as` to render as a non-interactive element:
+
+```svelte
+<script>
+  import { Link } from 'svelte-routing';
+</script>
+
+<Link to="/offers">
+  <brick-button-v9
+    data-label="See other subscriptions"
+    data-version="outlined"
+    data-as="span"
+  />
+</Link>
+```
+
+### React/Vue
+
+```javascript
+import '@amedia/brick-button';
+
+// React
+function MyComponent() {
+  return (
+    <brick-button-v9
+      data-label="Click me"
+      data-version="primary"
+      onClick={() => console.log('clicked')}
+    />
+  );
+}
+
+// Vue
+<template>
+  <brick-button-v9
+    data-label="Click me"
+    data-version="primary"
+    @click="handleClick"
+  />
+</template>
+```
+
+## Programmatic Usage
+
+```javascript
+import { BrickButton } from '@amedia/brick-button';
+
+const button = new BrickButton({
+  dataLabel: 'My Button',
+  dataVersion: 'primary',
+  dataSize: 'medium',
+});
+
+// Set click handler
+button.onClick = (event) => {
+  console.log('Button clicked!', event);
+};
+
+// Add to DOM
+document.body.appendChild(button);
+
+// Programmatically focus the button
+button.focus();
+```
+
+## Server-Side Rendering
+
+```javascript
+import { renderBrickButton } from '@amedia/brick-button/template';
+
+const buttonHTML = renderBrickButton({
+  dataLabel: 'Server Rendered',
+  dataVersion: 'primary',
+  dataLinkto: '/page',
+});
+
+// Include CSS file
+// <link rel="stylesheet" href="https://assets.acdn.no/pkg/@amedia/brick-button/v9/css/styles.css">
+```
+
+## Accessibility
+
+- Adheres to **WCAG 2.1 AA** guidelines
+- Full ARIA attributes support for screen readers
+- Keyboard navigation support (Enter/Space for buttons, Enter for links)
+- Focus visible states with clear outline
+- Disabled state prevents interaction and is communicated to assistive technology
+- Icon-only buttons require `data-aria-label` for proper accessibility
+- Proper semantic HTML (`<button>` vs `<a>`) based on behavior
+
+## Analytics Integration
+
+Brick-button supports ADP (Amedia Data Platform) tracking:
+
+```html
+<brick-button-v9
+  data-label="Subscribe Now"
+  data-version="primary"
+  data-adplabel="Subscribe CTA"
+  data-adpvalue="homepage-hero"
+>
+</brick-button-v9>
+```
+
+## Common Patterns
+
+### Call-to-Action Button
+
+```html
+<brick-button-v9
+  data-label="Start Free Trial"
+  data-version="primary"
+  data-size="medium"
+  data-adplabel="CTA - Free Trial"
+>
+</brick-button-v9>
+```
+
+### Modal Trigger with ARIA
+
+```html
+<brick-button-v9
+  data-label="Open Settings"
+  data-version="secondary"
+  data-aria-controls="settings-modal"
+  data-aria-expanded="false"
+  data-icon-id="settings"
+>
+</brick-button-v9>
+```
+
+### Toggle Button
+
+```html
+<brick-button-v9
+  data-label="Follow"
+  data-version="outlined"
+  data-aria-pressed="false"
+>
+</brick-button-v9>
+```
+
+### Navigation with Icon
+
+```html
+<brick-button-v9
+  data-label="Next"
+  data-version="primary"
+  data-linkto="/next-page"
+  data-icon-id="arrow-right"
+  data-iconplacement="right"
+>
+</brick-button-v9>
+```
+
+## Styling and CSS Properties
+
+Customize button appearance using CSS custom properties:
+
+```css
+brick-button-v9 {
+  /* Width control */
+  --b-button-width: 100%;
+
+  /* Height control */
+  --b-button-height: 3rem;
+
+  /* Border width */
+  --b-button-border: 2px;
+
+  /* Border radius */
+  --b-button-radii: 8px;
+
+  /* Content alignment */
+  --b-button-justify: flex-start;
+}
+```
+
+### Color Overrides
+
+```css
+brick-button-v9 {
+  /* Primary button colors */
+  --brick-colors-buttonPrimaryBg: var(--brick-colors-utilityWarningBg);
+  --brick-colors-buttonPrimaryHoverBg: var(--brick-colors-utilityWarningBg);
+  --brick-colors-buttonPrimaryActiveBg: var(--brick-colors-utilityWarningBg);
+  --brick-colors-buttonPrimaryFg: var(--brick-colors-utilityWarningFg);
+}
+```
+
+**Note:** When overriding colors, ensure your customizations adhere to WCAG 2.1 AA contrast requirements.
+
+## Technical Details
+
+- **Custom Element**: `brick-button-v9`
+- **Base Class**: BrickElement
+- **Dependencies**:
+  - @amedia/brick-tokens (design tokens)
+  - @amedia/brick-icon (icon support)
+  - @amedia/brick-template (base class)
+- **Renders as**: `<button>` (default) or `<a>` (when data-linkto is set) or `<span>`/`<div>` (when data-as is set)
+- **SSR Compatible**: Yes, with hydration support
+- **Framework**: Framework-agnostic web component
+
+## Important Notes
+
+- When `data-linkto` is provided, the component renders as an `<a>` tag; otherwise, it renders as a `<button>` tag
+- When `data-as` is set to `span` or `div`, renders as non-interactive element (useful for wrapping with framework router components)
+- Icon-only buttons automatically get rounded background styling
+- The component observes attribute changes and updates the DOM reactively for `data-label`, `data-icon-id`, `data-icontext`, `data-linkto`, and all ARIA attributes
+- Do not nest interactive elements inside brick-button when using framework routers - use `data-as` instead
+- Version 9.0.0 removed CommonJS support and changed `data-iconid` to `data-icon-id`
+
+## Version
+
+Current version: 9.3.1