@amedia/brick-mcp 0.1.2 → 0.1.4

package/data/components/brick-share.md

@@ -0,0 +1,335 @@
+---
+name: brick-share
+version: 0.3.12
+selector: brick-share
+category: Navigation
+tags: [share, social, web-share-api, clipboard, copy, gift, toast, url]
+use_cases: [article-sharing, social-sharing, url-copying, gift-articles, content-distribution]
+related: [brick-button, brick-toast, brick-tokens]
+---
+
+# Brick Share
+
+A versatile sharing component that supports native Web Share API, clipboard copying, and custom share functionality with toast feedback for success and error states.
+
+## Key Capabilities
+
+- Three sharing modes: share, copy, and gift
+- Native Web Share API support with automatic fallback to clipboard
+- Integration with Pushapp for app-specific sharing
+- Automatic toast notifications for success and error states
+- Customizable labels and aria-labels for accessibility
+- Icon-only or label-only display modes
+- Automatic URL detection (uses current page URL if not specified)
+- Server-side rendering support
+
+## Props/Attributes
+
+| Attribute            | Type                          | Default          | Required | Description                                                        |
+| -------------------- | ----------------------------- | ---------------- | -------- | ------------------------------------------------------------------ |
+| `data-version`       | `"share" \| "copy" \| "gift"` | `"share"`        | no       | Sharing mode and visual style                                      |
+| `data-url`           | string                        | Current page URL | no       | URL to share or copy                                               |
+| `data-title`         | string                        | -                | no       | Title for native share dialog                                      |
+| `data-text`          | string                        | -                | no       | Additional text for native share dialog                            |
+| `data-share-label`   | string                        | -                | no       | Custom button label text                                           |
+| `data-aria-label`    | string                        | -                | no       | ARIA label for accessibility                                       |
+| `data-copy-success`  | string                        | Default message  | no       | Custom success toast message when URL is copied                    |
+| `data-copy-error`    | string                        | Default message  | no       | Custom error toast message when copying fails                      |
+| `data-copy-status`   | `"success" \| "error"`        | -                | no       | Manually trigger toast display (for testing/demo)                  |
+| `data-label`         | string                        | -                | no       | Set to "false" to hide label (icon-only mode)                      |
+| `data-icon`          | string                        | -                | no       | Set to "false" to hide icon (label-only mode)                      |
+
+## Examples
+
+### Basic Share Button
+
+```html
+<brick-share
+  data-version="share"
+>
+</brick-share>
+```
+
+### Share Specific URL
+
+```html
+<brick-share
+  data-version="share"
+  data-url="https://amedia.no"
+  data-title="Lenke til Amedia.no"
+  data-text="Jeg vil gjerne dele denne med deg"
+>
+</brick-share>
+```
+
+### Copy to Clipboard
+
+```html
+<brick-share
+  data-version="copy"
+  data-url="https://amedia.no"
+  data-copy-success="Kopiert lenken!"
+  data-copy-error="Det oppstod en feil"
+>
+</brick-share>
+```
+
+### Gift Article
+
+```html
+<brick-share
+  data-version="gift"
+  data-share-label="Gi bort"
+  data-aria-label="Kopierer lenke for å gi bort artikkelen til en annen leser gratis"
+  data-copy-success="Kopiert lenken!"
+  data-copy-error="Det oppstod en feil"
+>
+</brick-share>
+```
+
+### Custom Label
+
+```html
+<brick-share
+  data-url="https://amedia.no"
+  data-share-label="Del artikkelen"
+>
+</brick-share>
+```
+
+### Icon Only
+
+```html
+<brick-share
+  data-url="https://amedia.no"
+  data-title="Lenke til Amedia.no"
+  data-version="share"
+  data-label="false"
+>
+</brick-share>
+```
+
+### Label Only (No Icon)
+
+```html
+<brick-share
+  data-share-label="Del"
+  data-icon="false"
+>
+</brick-share>
+```
+
+## Framework Integration
+
+### JavaScript
+
+```javascript
+// Get share button element
+const shareButton = document.querySelector('brick-share');
+
+// Programmatically set URL
+shareButton.dataUrl = 'https://example.com';
+shareButton.dataTitle = 'Check this out!';
+```
+
+### Listen for Share Events
+
+```javascript
+const shareButton = document.querySelector('brick-share');
+
+shareButton.addEventListener('click', (event) => {
+  console.log('Share button clicked');
+});
+```
+
+## Server-Side Rendering
+
+```javascript
+import { renderBrickShare } from '@amedia/brick-share/template';
+
+const html = renderBrickShare({
+  dataVersion: 'share',
+  dataUrl: 'https://amedia.no',
+  dataShareLabel: 'Del artikkelen',
+  dataCopySuccess: 'Kopiert!',
+  dataCopyError: 'Kunne ikke kopiere',
+});
+```
+
+## Sharing Behavior
+
+### Web Share API (Native)
+
+When available (mobile devices and modern browsers), the component uses the native Web Share API:
+
+```javascript
+navigator.share({
+  url: 'https://example.com',
+  title: 'Article title',
+  text: 'Additional text',
+});
+```
+
+### Clipboard Fallback
+
+If Web Share API is not available, the component falls back to copying the URL to clipboard and shows a toast notification.
+
+### Pushapp Integration
+
+The component automatically detects and uses Pushapp share functionality when available:
+
+```javascript
+window.pushapp.share({
+  url: 'https://example.com',
+  title: 'Article title',
+  text: 'Additional text',
+});
+```
+
+## Toast Notifications
+
+The component integrates with `brick-toast` to display feedback:
+
+- **Success**: Shows when URL is successfully copied to clipboard
+- **Error**: Shows when copying fails
+
+```html
+<!-- Success toast appears automatically -->
+<brick-share
+  data-version="copy"
+  data-copy-success="Lenken er kopiert!"
+>
+</brick-share>
+
+<!-- Error toast appears on failure -->
+<brick-share
+  data-version="copy"
+  data-copy-error="Kunne ikke kopiere lenken"
+>
+</brick-share>
+```
+
+## Accessibility
+
+- Full keyboard navigation support
+- Customizable ARIA labels via `data-aria-label`
+- Focus visible states
+- Screen reader friendly button labels
+- Semantic button element for proper interaction
+
+## Common Patterns
+
+### Article Share Section
+
+```html
+<div class="article-share">
+  <brick-share
+    data-version="share"
+    data-share-label="Del artikkelen"
+    data-copy-success="Lenken er kopiert!"
+  >
+  </brick-share>
+</div>
+```
+
+### Multiple Share Options
+
+```html
+<div class="share-options">
+  <brick-share
+    data-version="share"
+    data-share-label="Del"
+  >
+  </brick-share>
+
+  <brick-share
+    data-version="copy"
+    data-share-label="Kopier lenke"
+    data-copy-success="Kopiert!"
+  >
+  </brick-share>
+
+  <brick-share
+    data-version="gift"
+    data-share-label="Gi bort"
+    data-copy-success="Lenken er kopiert!"
+  >
+  </brick-share>
+</div>
+```
+
+### Compact Share Bar
+
+```html
+<div class="compact-share">
+  <!-- Icon-only buttons -->
+  <brick-share
+    data-version="share"
+    data-label="false"
+    data-aria-label="Del artikkelen"
+  >
+  </brick-share>
+
+  <brick-share
+    data-version="copy"
+    data-label="false"
+    data-aria-label="Kopier lenke"
+    data-copy-success="Kopiert!"
+  >
+  </brick-share>
+</div>
+```
+
+## Version Variants
+
+### Share Version
+
+Default sharing mode with share icon. Uses Web Share API when available.
+
+```html
+<brick-share data-version="share"></brick-share>
+```
+
+### Copy Version
+
+Displays copy icon and always copies to clipboard (does not invoke Web Share API).
+
+```html
+<brick-share data-version="copy"></brick-share>
+```
+
+### Gift Version
+
+Special variant for gifting articles, typically with custom messaging.
+
+```html
+<brick-share data-version="gift" data-share-label="Gi bort"></brick-share>
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-share`
+- **Base Class**: BrickElement
+- **Dependencies**:
+  - @amedia/brick-button (button component)
+  - @amedia/brick-toast (toast notifications)
+  - @amedia/brick-template (base class)
+  - @amedia/brick-tokens (design tokens)
+- **Renders as**: Button element using brick-button
+- **SSR Compatible**: Yes, with template function
+- **Browser APIs**: Web Share API, Clipboard API
+
+## Important Notes
+
+- If `data-url` is not provided, the component uses `window.location.href` (current page URL)
+- The Web Share API is only available in secure contexts (HTTPS)
+- Clipboard API requires user interaction (button click) to work
+- Toast notifications require `brick-toast` to be available on the page
+- Set `data-label="false"` for icon-only mode (accessibility requires `data-aria-label`)
+- Set `data-icon="false"` for label-only mode
+- The component automatically detects and prioritizes: Web Share API → Pushapp → Clipboard
+- `data-copy-status` is primarily for testing/demo purposes to manually trigger toasts
+
+## Version
+
+Current version: 0.3.12

package/data/components/brick-stepper.md

@@ -0,0 +1,319 @@
+---
+name: brick-stepper
+version: 1.0.18
+selector: brick-stepper-v1
+category: Navigation
+tags: [stepper, progress, steps, wizard, multi-step, process, indicator, accessibility]
+use_cases: [checkout-flow, multi-step-forms, onboarding, wizard, progress-tracking, registration]
+related: [brick-icon, brick-tokens]
+---
+
+# Brick Stepper
+
+A progress indicator component that displays the current step in a multi-step process with optional labels, icons, and visual feedback for completed and upcoming steps.
+
+## Key Capabilities
+
+- Displays numbered steps with current step indicator
+- Supports ascending (left-to-right) and descending (right-to-left) order
+- Optional labels for each step (e.g., "Step 1", "Step 2")
+- Visual distinction between completed, current, and upcoming steps
+- Optional checkmark icons for completed steps
+- Optional lock icons for incomplete steps
+- Fully accessible with ARIA labels and semantic HTML
+- Server-side rendering support
+
+## Props/Attributes
+
+| Attribute                 | Type              | Default               | Required | Description                                                        |
+| ------------------------- | ----------------- | --------------------- | -------- | ------------------------------------------------------------------ |
+| `data-steps`              | string (number)   | -                     | yes      | Total number of steps to render                                    |
+| `data-steps-current`      | string (number)   | -                     | no*      | Current step number (sets aria-current attribute)                  |
+| `data-steps-completed`    | string (number)   | -                     | no*      | Number of completed steps (alternative to data-steps-current)      |
+| `data-steps-order`        | `"asc" \| "desc"` | `"asc"`               | no       | Step order: "asc" (1→n) or "desc" (n→1)                            |
+| `data-steps-aria-label`   | string            | `"Fremdriftsindikator"` | no       | ARIA label for the stepper list                                    |
+| `data-steps-label`        | string            | -                     | no       | Label prefix for each step (e.g., "Steg" → "Steg 1", "Steg 2")    |
+| `data-steps-icon-check`   | string            | -                     | no       | Set to "true" to show checkmark icon on completed steps            |
+| `data-steps-icon-lock`    | string            | -                     | no       | Set to "true" to show lock icon on incomplete steps                |
+
+*Either `data-steps-current` or `data-steps-completed` must be provided.
+
+## Examples
+
+### Basic Stepper
+
+```html
+<brick-stepper-v1
+  data-steps="7"
+  data-steps-current="4"
+>
+</brick-stepper-v1>
+```
+
+### Stepper with Labels
+
+```html
+<brick-stepper-v1
+  data-steps="5"
+  data-steps-current="2"
+  data-steps-label="Steg"
+>
+</brick-stepper-v1>
+```
+
+### Reversed Order (Right-to-Left)
+
+```html
+<brick-stepper-v1
+  data-steps="7"
+  data-steps-current="4"
+  data-steps-order="desc"
+>
+</brick-stepper-v1>
+```
+
+### With Icons
+
+```html
+<brick-stepper-v1
+  data-steps="5"
+  data-steps-current="3"
+  data-steps-label="Steg"
+  data-steps-icon-check="true"
+  data-steps-icon-lock="true"
+>
+</brick-stepper-v1>
+```
+
+### Using Completed Instead of Current
+
+```html
+<brick-stepper-v1
+  data-steps="5"
+  data-steps-completed="2"
+  data-steps-label="Steg"
+>
+</brick-stepper-v1>
+```
+
+### Custom ARIA Label
+
+```html
+<brick-stepper-v1
+  data-steps="4"
+  data-steps-current="2"
+  data-steps-aria-label="Checkout process"
+>
+</brick-stepper-v1>
+```
+
+### Checkout Flow Example
+
+```html
+<brick-stepper-v1
+  data-steps="4"
+  data-steps-current="2"
+  data-steps-label="Step"
+  data-steps-icon-check="true"
+  data-steps-icon-lock="true"
+  data-steps-aria-label="Checkout progress"
+>
+</brick-stepper-v1>
+```
+
+## Programmatic Usage
+
+### Update Current Step
+
+```javascript
+const stepper = document.querySelector('brick-stepper-v1');
+
+// Move to next step
+stepper.dataStepsCurrent = '3';
+
+// Enable icons
+stepper.dataStepsIconCheck = 'true';
+stepper.dataStepsIconLock = 'true';
+```
+
+## Server-Side Rendering
+
+```javascript
+import { renderBrickStepper } from '@amedia/brick-stepper/template';
+
+const html = renderBrickStepper({
+  dataSteps: '5',
+  dataStepsCurrent: '2',
+  dataStepsLabel: 'Steg',
+  dataStepsIconCheck: 'true',
+  dataStepsAriaLabel: 'Registration progress',
+});
+```
+
+## Visual States
+
+### Step States
+
+The component provides visual distinction for three step states:
+
+1. **Completed steps**: Steps before the current step (or within completed count)
+   - Styled with completed visual state
+   - Optional checkmark icon
+
+2. **Current step**: The active step in the process
+   - Receives `aria-current="step"` attribute
+   - Visual emphasis styling
+
+3. **Upcoming steps**: Steps after the current step
+   - Default styling
+   - Optional lock icon
+
+### Step Order
+
+- **Ascending (`data-steps-order="asc"`)**: Steps numbered 1 → n (left to right)
+- **Descending (`data-steps-order="desc"`)**: Steps numbered n → 1 (right to left, reversed)
+
+## Accessibility
+
+- Uses semantic `<ol>` (ordered list) element
+- Current step marked with `aria-current="step"`
+- Customizable `aria-label` for the list container
+- Proper list item semantics for screen readers
+- Visual and non-visual indication of progress
+- Keyboard navigation support through standard list semantics
+
+## Common Patterns
+
+### Multi-Step Form
+
+```html
+<form>
+  <brick-stepper-v1
+    data-steps="3"
+    data-steps-current="1"
+    data-steps-label="Step"
+    data-steps-aria-label="Registration form progress"
+  >
+  </brick-stepper-v1>
+
+  <!-- Form content here -->
+</form>
+```
+
+### Checkout Process
+
+```html
+<brick-stepper-v1
+  data-steps="4"
+  data-steps-current="2"
+  data-steps-label="Step"
+  data-steps-icon-check="true"
+  data-steps-icon-lock="true"
+  data-steps-aria-label="Checkout process"
+>
+</brick-stepper-v1>
+
+<!-- Steps: Cart → Shipping → Payment → Confirmation -->
+```
+
+### Onboarding Wizard
+
+```html
+<brick-stepper-v1
+  data-steps="5"
+  data-steps-current="3"
+  data-steps-label="Steg"
+  data-steps-icon-check="true"
+  data-steps-aria-label="Onboarding wizard"
+>
+</brick-stepper-v1>
+```
+
+### Reverse Flow (Countdown)
+
+```html
+<brick-stepper-v1
+  data-steps="7"
+  data-steps-current="5"
+  data-steps-order="desc"
+  data-steps-label="Dag"
+  data-steps-aria-label="Days remaining"
+>
+</brick-stepper-v1>
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  let currentStep = 1;
+
+  function nextStep() {
+    currentStep++;
+  }
+
+  function prevStep() {
+    currentStep--;
+  }
+</script>
+
+<brick-stepper-v1
+  data-steps="5"
+  data-steps-current={currentStep.toString()}
+  data-steps-label="Step"
+/>
+
+<button on:click={prevStep}>Previous</button>
+<button on:click={nextStep}>Next</button>
+```
+
+### React
+
+```jsx
+import { useState } from 'react';
+
+function CheckoutFlow() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  return (
+    <>
+      <brick-stepper-v1
+        data-steps="4"
+        data-steps-current={currentStep.toString()}
+        data-steps-label="Step"
+        data-steps-icon-check="true"
+      />
+
+      <button onClick={() => setCurrentStep(currentStep - 1)}>Back</button>
+      <button onClick={() => setCurrentStep(currentStep + 1)}>Next</button>
+    </>
+  );
+}
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-stepper-v1`
+- **Base Class**: BrickElement
+- **Dependencies**:
+  - @amedia/brick-icon (for check and lock icons)
+  - @amedia/brick-template (base class)
+  - @amedia/brick-tokens (design tokens)
+- **Renders as**: `<ol>` (ordered list) with `<li>` items
+- **SSR Compatible**: Yes, with template function
+
+## Important Notes
+
+- Either `data-steps-current` or `data-steps-completed` must be provided
+- Step numbers are 1-indexed (first step is "1", not "0")
+- When `data-steps-order="desc"`, steps are visually reversed but still numbered correctly
+- Icons require `data-steps-icon-check` or `data-steps-icon-lock` to be set to "true" (string)
+- The component is purely presentational - it does not handle step navigation logic
+- Labels are automatically numbered: if `data-steps-label="Steg"`, steps show as "Steg 1", "Steg 2", etc.
+- The default ARIA label is in Norwegian: "Fremdriftsindikator" - customize for other languages
+
+## Version
+
+Current version: 1.0.18