@amedia/brick-mcp 1.0.12 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/data/components/brick-share.md +165 -230
  2. package/data/components-metadata.json +32 -32
  3. package/dist/data/components/brick-share.md +165 -230
  4. package/dist/data/components-metadata.json +32 -32
  5. package/package.json +30 -30
package/data/components/brick-share.md CHANGED
@@ -1,338 +1,273 @@
1
1
  ---
2
2
  name: brick-share
3
- version: 0.4.3
4
- selector: brick-share
3
+ version: 2.0.0
4
+ selector: brick-share-v2
5
5
  category: Navigation
6
- tags: [share, social, web-share-api, clipboard, copy, gift, toast, url]
6
+ tags: [share, social, web-share-api, clipboard, copy, gift, toast, url, utm]
7
7
  use_cases: [article-sharing, social-sharing, url-copying, gift-articles, content-distribution]
8
8
  related: [brick-button, brick-toast, brick-tokens]
9
9
  ---
10
10
 
11
11
  # Brick Share
12
12
 
13
- A versatile sharing component that supports native Web Share API, clipboard copying, and custom share functionality with toast feedback for success and error states.
13
+ A sharing button that uses native Web Share API on mobile or falls back to clipboard copy on desktop, with optional toast feedback.
14
14
 
15
15
  ## Key Capabilities
16
16
 
17
- - Three sharing modes: share, copy, and gift
18
- - Native Web Share API support with automatic fallback to clipboard
19
- - Integration with Pushapp for app-specific sharing
20
- - Automatic toast notifications for success and error states
21
- - Customizable labels and aria-labels for accessibility
22
- - Icon-only or label-only display modes
23
- - Automatic URL detection (uses current page URL if not specified)
24
- - UTM parameter support for campaign tracking (since v0.4.0)
25
- - Uses native sharing on mobile/tablet and copy-to-clipboard on desktop
26
- - Server-side rendering support
17
+ - Three sharing modes: `share`, `copy`, and `gift`
18
+ - Automatically uses native Web Share API on mobile; falls back to clipboard on desktop
19
+ - Pushapp integration detected and used automatically when available
20
+ - Toast notifications (via `brick-toast`) for clipboard copy success and error states
21
+ - Icon-only or label-only display, or both
22
+ - Automatic URL fallback to `window.location.href` when `data-url` is absent or unparseable
23
+ - UTM parameter appending to shared URLs
24
+ - Server-side rendering support via `/template` submodule
27
25
 
28
26
  ## Props/Attributes
29
27
 
30
- | Attribute | Type | Default | Required | Description |
31
- | -------------------- | ----------------------------- | ---------------- | -------- | ------------------------------------------------------------------ |
32
- | `data-version` | `"share" \| "copy" \| "gift"` | `"share"` | no | Sharing mode and visual style |
33
- | `data-url` | string | Current page URL | no | URL to share or copy |
34
- | `data-title` | string | - | no | Title for native share dialog |
35
- | `data-text` | string | - | no | Additional text for native share dialog |
36
- | `data-share-label` | string | - | no | Custom button label text |
37
- | `data-aria-label` | string | - | no | ARIA label for accessibility |
38
- | `data-copy-success` | string | Default message | no | Custom success toast message when URL is copied |
39
- | `data-copy-error` | string | Default message | no | Custom error toast message when copying fails |
40
- | `data-copy-status` | `"success" \| "error"` | - | no | Manually trigger toast display (for testing/demo) |
41
- | `data-label` | string | - | no | Set to "false" to hide label (icon-only mode) |
42
- | `data-icon` | string | - | no | Set to "false" to hide icon (label-only mode) |
43
- | `data-utm` | string | - | no | UTM parameters to append as query params to the shared URL |
44
-
45
- ## Examples
46
-
47
- ### Basic Share Button
28
+ | Attribute | Type | Default | Required | Description |
29
+ | ------------------- | ----------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------ |
30
+ | `data-aria-label` | string | — | **yes** | ARIA label for the button. Throws at render time if missing. |
31
+ | `data-version` | `"share" \| "copy" \| "gift"` | `"share"` | no | Sharing mode. Determines icon and behavior. |
32
+ | `data-url` | string | Current page URL | no | URL to share or copy. Falls back to `window.location.href` if absent or invalid. |
33
+ | `data-share-label` | string | — | no | Button label text. Omit or pass empty string for icon-only mode. |
34
+ | `data-title` | string | — | no | Title for native share dialog. |
35
+ | `data-text` | string | — | no | Body text for native share dialog. |
36
+ | `data-copy-success` | string | Default message | no | Custom success toast message shown after clipboard copy. |
37
+ | `data-copy-error` | string | Default message | no | Custom error toast message shown when clipboard copy fails. |
38
+ | `data-copy-status` | `"success" \| "error"` | — | no | Manually trigger toast display (useful for testing/demo). |
39
+ | `data-icon` | string | — | no | Set to `"false"` to hide the icon (label-only mode). |
40
+ | `data-utm` | string | — | no | UTM query string (e.g. `utm_source=share&utm_medium=social`) appended to shared URL. |
41
+
42
+ ## Usage
43
+
44
+ ### Server-side rendering (preferred)
45
+
46
+ ```ts
47
+ import { renderBrickShare } from '@amedia/brick-share/template';
48
48
 
49
- ```html
50
- <brick-share
51
- data-version="share"
52
- >
53
- </brick-share>
49
+ const html = renderBrickShare({
50
+ dataAriaLabel: 'Del denne artikkelen med andre',
51
+ dataShareLabel: 'Del',
52
+ dataVersion: 'share',
53
+ dataUrl: 'https://amedia.no',
54
+ });
54
55
  ```
55
56
 
56
- ### Share Specific URL
57
+ Copy mode with custom toast messages:
57
58
 
58
- ```html
59
- <brick-share
60
- data-version="share"
61
- data-url="https://amedia.no"
62
- data-title="Lenke til Amedia.no"
63
- data-text="Jeg vil gjerne dele denne med deg"
64
- >
65
- </brick-share>
59
+ ```ts
60
+ const html = renderBrickShare({
61
+ dataAriaLabel: 'Kopier lenke til artikkelen',
62
+ dataShareLabel: 'Kopier lenke',
63
+ dataVersion: 'copy',
64
+ dataUrl: 'https://amedia.no',
65
+ dataCopySuccess: 'Kopiert lenken!',
66
+ dataCopyError: 'Det oppstod en feil',
67
+ });
66
68
  ```
67
69
 
68
- ### Copy to Clipboard
70
+ Icon-only (no label):
69
71
 
70
- ```html
71
- <brick-share
72
- data-version="copy"
73
- data-url="https://amedia.no"
74
- data-copy-success="Kopiert lenken!"
75
- data-copy-error="Det oppstod en feil"
76
- >
77
- </brick-share>
72
+ ```ts
73
+ const html = renderBrickShare({
74
+ dataAriaLabel: 'Del denne artikkelen med andre',
75
+ dataVersion: 'share',
76
+ dataUrl: 'https://amedia.no',
77
+ });
78
78
  ```
79
79
 
80
- ### Gift Article
80
+ With UTM tracking:
81
81
 
82
- ```html
83
- <brick-share
84
- data-version="gift"
85
- data-share-label="Gi bort"
86
- data-aria-label="Kopierer lenke for å gi bort artikkelen til en annen leser gratis"
87
- data-copy-success="Kopiert lenken!"
88
- data-copy-error="Det oppstod en feil"
89
- >
90
- </brick-share>
82
+ ```ts
83
+ const html = renderBrickShare({
84
+ dataAriaLabel: 'Del denne artikkelen med andre',
85
+ dataShareLabel: 'Del',
86
+ dataUrl: 'https://amedia.no',
87
+ dataUtm: 'utm_source=partnerxyz&utm_medium=referral',
88
+ });
91
89
  ```
92
90
 
93
- ### Custom Label
91
+ ### Client-side (declarative HTML)
94
92
 
95
93
  ```html
96
- <brick-share
97
- data-url="https://amedia.no"
98
- data-share-label="Del artikkelen"
99
- >
100
- </brick-share>
101
- ```
102
-
103
- ### Icon Only
94
+ <script type="module" src="https://eik.api.no/pkg/@amedia/brick-share/v1/index.js"></script>
104
95
 
105
- ```html
106
- <brick-share
107
- data-url="https://amedia.no"
108
- data-title="Lenke til Amedia.no"
96
+ <brick-share-v2
97
+ data-aria-label="Del denne artikkelen med andre"
98
+ data-share-label="Del"
109
99
  data-version="share"
110
- data-label="false"
111
- >
112
- </brick-share>
100
+ data-url="https://amedia.no"
101
+ ></brick-share-v2>
113
102
  ```
114
103
 
115
- ### Label Only (No Icon)
104
+ Gift mode:
116
105
 
117
106
  ```html
118
- <brick-share
119
- data-share-label="Del"
120
- data-icon="false"
121
- >
122
- </brick-share>
123
- ```
124
-
125
- ## Framework Integration
126
-
127
- ### JavaScript
128
-
129
- ```javascript
130
- // Get share button element
131
- const shareButton = document.querySelector('brick-share');
132
-
133
- // Programmatically set URL
134
- shareButton.dataUrl = 'https://example.com';
135
- shareButton.dataTitle = 'Check this out!';
136
- ```
137
-
138
- ### Listen for Share Events
139
-
140
- ```javascript
141
- const shareButton = document.querySelector('brick-share');
142
-
143
- shareButton.addEventListener('click', (event) => {
144
- console.log('Share button clicked');
145
- });
107
+ <brick-share-v2
108
+ data-aria-label="Kopier lenke for å gi bort artikkelen gratis"
109
+ data-share-label="Gi bort"
110
+ data-version="gift"
111
+ data-copy-success="Kopiert lenken!"
112
+ data-copy-error="Det oppstod en feil"
113
+ ></brick-share-v2>
146
114
  ```
147
115
 
148
- ## Server-Side Rendering
149
-
150
- ```javascript
151
- import { renderBrickShare } from '@amedia/brick-share/template';
116
+ Create via JavaScript:
152
117
 
153
- const html = renderBrickShare({
154
- dataVersion: 'share',
155
- dataUrl: 'https://amedia.no',
156
- dataShareLabel: 'Del artikkelen',
157
- dataCopySuccess: 'Kopiert!',
158
- dataCopyError: 'Kunne ikke kopiere',
159
- });
118
+ ```js
119
+ const element = document.createElement('brick-share-v2');
120
+ element.dataset.ariaLabel = 'Del denne artikkelen med andre';
121
+ element.dataset.shareLabel = 'Del';
122
+ element.dataset.url = 'https://amedia.no';
123
+ document.body.appendChild(element);
160
124
  ```
161
125
 
162
- ## Sharing Behavior
126
+ ## Version Variants
163
127
 
164
- ### Web Share API (Native)
128
+ ### Share version
165
129
 
166
- When available (mobile devices and modern browsers), the component uses the native Web Share API:
130
+ Default mode. Uses Web Share API on mobile, falls back to clipboard on desktop.
167
131
 
168
- ```javascript
169
- navigator.share({
170
- url: 'https://example.com',
171
- title: 'Article title',
172
- text: 'Additional text',
173
- });
132
+ ```html
133
+ <brick-share-v2
134
+ data-version="share"
135
+ data-aria-label="Del denne artikkelen med andre"
136
+ data-share-label="Del"
137
+ ></brick-share-v2>
174
138
  ```
175
139
 
176
- ### Clipboard Fallback
140
+ ### Copy version
177
141
 
178
- If Web Share API is not available, the component falls back to copying the URL to clipboard and shows a toast notification.
142
+ Always copies to clipboard — does not invoke the Web Share API.
179
143
 
180
- ### Pushapp Integration
181
-
182
- The component automatically detects and uses Pushapp share functionality when available:
183
-
184
- ```javascript
185
- window.pushapp.share({
186
- url: 'https://example.com',
187
- title: 'Article title',
188
- text: 'Additional text',
189
- });
144
+ ```html
145
+ <brick-share-v2
146
+ data-version="copy"
147
+ data-aria-label="Kopier lenke til artikkelen"
148
+ data-share-label="Kopier lenke"
149
+ data-copy-success="Kopiert lenken!"
150
+ data-copy-error="Det oppstod en feil"
151
+ ></brick-share-v2>
190
152
  ```
191
153
 
192
- ## Toast Notifications
193
-
194
- The component integrates with `brick-toast` to display feedback:
154
+ ### Gift version
195
155
 
196
- - **Success**: Shows when URL is successfully copied to clipboard
197
- - **Error**: Shows when copying fails
156
+ For gifting articles. Copies a gift link to clipboard.
198
157
 
199
158
  ```html
200
- <!-- Success toast appears automatically -->
201
- <brick-share
202
- data-version="copy"
203
- data-copy-success="Lenken er kopiert!"
204
- >
205
- </brick-share>
206
-
207
- <!-- Error toast appears on failure -->
208
- <brick-share
209
- data-version="copy"
210
- data-copy-error="Kunne ikke kopiere lenken"
211
- >
212
- </brick-share>
159
+ <brick-share-v2
160
+ data-version="gift"
161
+ data-aria-label="Kopier lenke for å gi bort artikkelen gratis"
162
+ data-share-label="Gi bort"
163
+ data-copy-success="Kopiert lenken!"
164
+ data-copy-error="Det oppstod en feil"
165
+ ></brick-share-v2>
213
166
  ```
214
167
 
215
- ## Accessibility
216
-
217
- - Full keyboard navigation support
218
- - Customizable ARIA labels via `data-aria-label`
219
- - Focus visible states
220
- - Screen reader friendly button labels
221
- - Semantic button element for proper interaction
222
-
223
168
  ## Common Patterns
224
169
 
225
- ### Article Share Section
170
+ ### Article share section
226
171
 
227
172
  ```html
228
173
  <div class="article-share">
229
- <brick-share
174
+ <brick-share-v2
230
175
  data-version="share"
176
+ data-aria-label="Del denne artikkelen med andre"
231
177
  data-share-label="Del artikkelen"
232
178
  data-copy-success="Lenken er kopiert!"
233
- >
234
- </brick-share>
179
+ ></brick-share-v2>
235
180
  </div>
236
181
  ```
237
182
 
238
- ### Multiple Share Options
183
+ ### Multiple share options
239
184
 
240
185
  ```html
241
186
  <div class="share-options">
242
- <brick-share
187
+ <brick-share-v2
243
188
  data-version="share"
189
+ data-aria-label="Del denne artikkelen med andre"
244
190
  data-share-label="Del"
245
- >
246
- </brick-share>
191
+ ></brick-share-v2>
247
192
 
248
- <brick-share
193
+ <brick-share-v2
249
194
  data-version="copy"
195
+ data-aria-label="Kopier lenke til artikkelen"
250
196
  data-share-label="Kopier lenke"
251
197
  data-copy-success="Kopiert!"
252
- >
253
- </brick-share>
198
+ ></brick-share-v2>
254
199
 
255
- <brick-share
200
+ <brick-share-v2
256
201
  data-version="gift"
202
+ data-aria-label="Kopier lenke for å gi bort artikkelen gratis"
257
203
  data-share-label="Gi bort"
258
204
  data-copy-success="Lenken er kopiert!"
259
- >
260
- </brick-share>
205
+ ></brick-share-v2>
261
206
  </div>
262
207
  ```
263
208
 
264
- ### Compact Share Bar
209
+ ### Compact icon-only share bar
265
210
 
266
211
  ```html
267
212
  <div class="compact-share">
268
- <!-- Icon-only buttons -->
269
- <brick-share
213
+ <brick-share-v2
270
214
  data-version="share"
271
- data-label="false"
272
215
  data-aria-label="Del artikkelen"
273
- >
274
- </brick-share>
216
+ ></brick-share-v2>
275
217
 
276
- <brick-share
218
+ <brick-share-v2
277
219
  data-version="copy"
278
- data-label="false"
279
220
  data-aria-label="Kopier lenke"
280
221
  data-copy-success="Kopiert!"
281
- >
282
- </brick-share>
222
+ ></brick-share-v2>
283
223
  </div>
284
224
  ```
285
225
 
286
- ## Version Variants
287
-
288
- ### Share Version
289
-
290
- Default sharing mode with share icon. Uses Web Share API when available.
226
+ ### Label-only (no icon)
291
227
 
292
228
  ```html
293
- <brick-share data-version="share"></brick-share>
229
+ <brick-share-v2
230
+ data-icon="false"
231
+ data-aria-label="Del denne artikkelen med andre"
232
+ data-share-label="Del artikkelen"
233
+ ></brick-share-v2>
294
234
  ```
295
235
 
296
- ### Copy Version
297
-
298
- Displays copy icon and always copies to clipboard (does not invoke Web Share API).
236
+ ### Programmatically update the label
299
237
 
300
- ```html
301
- <brick-share data-version="copy"></brick-share>
238
+ ```js
239
+ const shareButton = document.querySelector('brick-share-v2');
240
+ shareButton.setAttribute('data-share-label', 'Kopiert!');
302
241
  ```
303
242
 
304
- ### Gift Version
243
+ ### Listen for share button clicks
305
244
 
306
- Special variant for gifting articles, typically with custom messaging.
307
-
308
- ```html
309
- <brick-share data-version="gift" data-share-label="Gi bort"></brick-share>
245
+ ```js
246
+ const shareButton = document.querySelector('brick-share-v2');
247
+ shareButton.addEventListener('click', () => {
248
+ console.log('Share button clicked');
249
+ });
310
250
  ```
311
251
 
312
- ## Technical Details
252
+ ## Accessibility
313
253
 
314
- - **Custom Element**: `brick-share`
315
- - **Base Class**: BrickElement
316
- - **Dependencies**:
317
- - @amedia/brick-button (button component)
318
- - @amedia/brick-toast (toast notifications)
319
- - @amedia/brick-template (base class)
320
- - @amedia/brick-tokens (design tokens)
321
- - **Renders as**: Button element using brick-button
322
- - **SSR Compatible**: Yes, with template function
323
- - **Browser APIs**: Web Share API, Clipboard API
254
+ - `data-aria-label` is **required** and throws an error if omitted — ensures every share button has a meaningful accessible name regardless of whether a visible label is shown.
255
+ - Keyboard navigation and focus management are handled by the internally rendered `brick-button`.
256
+ - For icon-only mode, the `data-aria-label` is the sole accessible label — make it descriptive (e.g. `"Del denne artikkelen med andre"`).
324
257
 
325
- ## Important Notes
258
+ ## Technical Details
326
259
 
327
- - If `data-url` is not provided, the component uses `window.location.href` (current page URL)
328
- - The Web Share API is only available in secure contexts (HTTPS)
329
- - Clipboard API requires user interaction (button click) to work
330
- - Toast notifications require `brick-toast` to be available on the page
331
- - Set `data-label="false"` for icon-only mode (accessibility requires `data-aria-label`)
332
- - Set `data-icon="false"` for label-only mode
333
- - The component automatically detects and prioritizes: Web Share API → Pushapp → Clipboard
334
- - `data-copy-status` is primarily for testing/demo purposes to manually trigger toasts
260
+ - **Package version**: `2.0.0`
261
+ - **Custom Element tag**: `brick-share-v2` — must match the `selector` in frontmatter
262
+ - **Dependencies**: `@amedia/brick-button`, `@amedia/brick-toast`, `@amedia/brick-template`, `@amedia/brick-tokens`
335
263
 
336
- ## Version
264
+ ## Important Notes
337
265
 
338
- Current version: 0.4.3
266
+ - **`data-aria-label` is required** — the render function throws `Error: brick-share: dataAriaLabel is required` if it is missing. This is a breaking change from v0.x where it was optional with built-in Norwegian defaults.
267
+ - **No default labels** — built-in fallback labels (`Kopier`, `Del`, `Gi bort`) were removed in v1.0. You must supply `data-share-label` explicitly, or omit it for icon-only mode.
268
+ - **Icon-only mode**: omit `data-share-label` (or pass an empty string). The old `data-label="false"` attribute is no longer supported.
269
+ - **Label-only mode**: set `data-icon="false"`.
270
+ - On desktop or when Web Share API is unavailable, the component automatically switches to clipboard copy regardless of `data-version="share"`.
271
+ - Clipboard API requires a secure context (HTTPS) and a user gesture.
272
+ - `data-copy-status` is primarily for testing — setting it programmatically triggers the toast.
273
+ - Toast notifications require `brick-toast` to be present; it is imported automatically when using the npm package.