@xsynaptic/share-kit 0.3.0 → 0.5.0

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.
package/README.md CHANGED
@@ -80,24 +80,35 @@ const payload: ShareKitPayload<Destination> = {
80
80
  </script>
81
81
  ```
82
82
 
83
- Every action in the dialog fires a `share-kit:action` event. Listen in the same script as `defineShareKit()`, before or after the call.
83
+ Every action in the dialog fires a `share-kit:action` event whose `detail` holds the `action`, the selected `destination` and, for an image, its `asset` id. Listen in the same script as `defineShareKit()`, before or after the call.
84
84
 
85
- If `settings.openHash` matches the URL hash, the dialog opens on load. Pick a fragment that no element id on the page uses, or the page also scrolls there.
85
+ Sharing and saving fire once they finish, with an `outcome`:
86
+
87
+ - `share`: `shared`, `dismissed`, `retry` (a slow download used up the tap), `saved` (the browser refused the file, so it downloaded instead) or `error`
88
+ - `share-link`, `share-text`: `shared`, `dismissed` or `error`
89
+ - `save`: `saved` or `error`
90
+
91
+ `shared` means the share sheet took it, not that it was posted.
92
+
93
+ A trigger can name a destination, as in `data-share-kit-trigger="instagram"`, to open the dialog with it selected. With a single destination, the dialog leaves out the destination row.
94
+
95
+ If `settings.openHash` matches the URL hash, the dialog opens on load. Pick a fragment that no element id on the page uses, or the page also scrolls there. When several elements share one, only the first on the page opens.
86
96
 
87
97
  `strings` in the payload overrides the dialog's wording by key, including `destination.<id>` and `hint.<id>`.
88
98
 
89
99
  ## Destinations
90
100
 
91
- The built-ins are `shareKitAnywhere`, `shareKitBluesky`, `shareKitFacebook`, `shareKitInstagram`, `shareKitInstagramStory`, `shareKitLinkedin`, `shareKitMastodon`, `shareKitMessages`, `shareKitPinterest`, `shareKitReddit`, `shareKitThreads` and `shareKitX`. Adjust one by spreading it (`{ ...shareKitMastodon, limit: 1000 }`), or write your own with `defineShareKitDestination`:
101
+ The built-ins are `shareKitAnywhere`, `shareKitBluesky`, `shareKitFacebook`, `shareKitInstagram`, `shareKitInstagramStory`, `shareKitLine`, `shareKitLinkedin`, `shareKitMastodon`, `shareKitMessages`, `shareKitPinterest`, `shareKitReddit`, `shareKitThreads` and `shareKitX`. Adjust one by spreading it (`{ ...shareKitMastodon, limit: 1000 }`), or write your own with `defineShareKitDestination`:
92
102
 
93
103
  ```ts
94
- export const line = defineShareKitDestination({
104
+ export const email = defineShareKitDestination({
95
105
  actions: { desktop: ['open-composer'], mobile: ['open-composer'] },
96
- composer: ({ text }) => `https://line.me/R/share?text=${encodeURIComponent(text)}`,
106
+ composer: ({ text, title }) =>
107
+ `mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(text)}`,
97
108
  count: shareKitCountLength,
98
- id: 'line',
109
+ id: 'email',
99
110
  images: [shareKitLandscapeFormat],
100
- label: 'LINE',
111
+ label: 'Email',
101
112
  shape: 'full',
102
113
  });
103
114
  ```
@@ -112,7 +123,7 @@ The dialog downloads the images in `assets` to save, copy or share them, so serv
112
123
 
113
124
  ## Icons
114
125
 
115
- The package ships no brand icons. Pass the ones you show to `defineShareKit({ icons })` as 24×24 SVG path data, keyed by destination id or by `close`, `more` and `qr`, or pass a function that returns a promise of that map to load them lazily. `shareKitInterfaceIcons` holds the five drawn for this package. For brand marks, [Simple Icons](https://simpleicons.org) has every built-in but LinkedIn.
126
+ The package ships no brand icons. Pass the ones you show to `defineShareKit({ icons })` as 24×24 SVG path data, keyed by destination id or by `close` and `more`, or pass a function that returns a promise of that map to load them lazily. `shareKitInterfaceIcons` holds the four drawn for this package. For brand marks, [Simple Icons](https://simpleicons.org) has every built-in but LinkedIn.
116
127
 
117
128
  ## Styles
118
129
 
package/dist/index.d.mts CHANGED
@@ -5,7 +5,8 @@ export declare function shareKitCountLength(text: string): number;
5
5
  export declare function shareKitCountGraphemes(text: string): number;
6
6
  export declare function shareKitCountUtf8(text: string): number;
7
7
  type ShareKitCounter = (text: string) => number;
8
- export declare function shareKitWithLinkCost(count: ShareKitCounter, cost: ((link: string) => number) | number): ShareKitCounter;
8
+ type LinkCost = ((link: string) => number) | number;
9
+ export declare function shareKitWithLinkCost(count: ShareKitCounter, cost: LinkCost): ShareKitCounter;
9
10
  interface ShareKitImageFormat {
10
11
  height: number;
11
12
  id: string;
@@ -35,7 +36,7 @@ type ShareKitImageFormats = readonly [ShareKitImageFormat, ...Array<ShareKitImag
35
36
  export declare function getShareKitImageFormats(destinations: ReadonlyArray<{
36
37
  images: ShareKitImageFormats;
37
38
  }>): ShareKitImageFormat[];
38
- type ShareKitActionKind = 'copy-caption' | 'open-composer' | 'share-image' | 'share-link' | 'share-text';
39
+ type ShareKitActionKind = 'copy-caption' | 'open-composer' | 'save-image' | 'share-image' | 'share-link' | 'share-text';
39
40
  type ShareKitDevice = 'desktop' | 'mobile';
40
41
  interface ShareKitComposerInput {
41
42
  description?: string;
@@ -99,7 +100,7 @@ export declare const shareKitFacebook: {
99
100
  };
100
101
  readonly composer: ({ url }: ShareKitComposerInput) => string;
101
102
  readonly count: typeof shareKitCountLength;
102
- readonly hint: "Facebook only takes the link. Your caption is copied, so paste it into your post.";
103
+ readonly hint: "Facebook only takes the link. Your text is copied, so paste it into your post.";
103
104
  readonly id: "facebook";
104
105
  readonly images: readonly [{
105
106
  readonly height: 630;
@@ -116,11 +117,11 @@ export declare const shareKitFacebook: {
116
117
  };
117
118
  export declare const shareKitInstagram: {
118
119
  readonly actions: {
119
- readonly desktop: readonly [];
120
+ readonly desktop: readonly ["save-image"];
120
121
  readonly mobile: readonly ["share-image"];
121
122
  };
122
123
  readonly count: typeof shareKitCountLength;
123
- readonly hint: "Links in Instagram captions aren't clickable. Point people to the link in your bio.";
124
+ readonly hint: "Your text is copied, so paste it as the caption. Links in it aren't clickable.";
124
125
  readonly id: "instagram";
125
126
  readonly images: readonly [{
126
127
  readonly height: 1350;
@@ -133,11 +134,11 @@ export declare const shareKitInstagram: {
133
134
  };
134
135
  export declare const shareKitInstagramStory: {
135
136
  readonly actions: {
136
- readonly desktop: readonly [];
137
+ readonly desktop: readonly ["save-image"];
137
138
  readonly mobile: readonly ["share-image"];
138
139
  };
139
140
  readonly count: typeof shareKitCountLength;
140
- readonly hint: "Add the link to your Story with a link sticker.";
141
+ readonly hint: "The link is copied, so add it to your Story with a link sticker.";
141
142
  readonly id: "instagram-story";
142
143
  readonly images: readonly [{
143
144
  readonly height: 1920;
@@ -158,7 +159,7 @@ export declare const shareKitLinkedin: {
158
159
  };
159
160
  readonly composer: ({ url }: ShareKitComposerInput) => string;
160
161
  readonly count: typeof shareKitCountLength;
161
- readonly hint: "LinkedIn only takes the link. Your caption is copied, so paste it into your post.";
162
+ readonly hint: "LinkedIn only takes the link. Your text is copied, so paste it into your post.";
162
163
  readonly id: "linkedin";
163
164
  readonly images: readonly [{
164
165
  readonly height: 630;
@@ -169,11 +170,29 @@ export declare const shareKitLinkedin: {
169
170
  readonly limit: 3000;
170
171
  readonly shape: "full";
171
172
  };
173
+ export declare const shareKitLine: {
174
+ readonly actions: {
175
+ readonly desktop: readonly ["open-composer"];
176
+ readonly mobile: readonly ["open-composer"];
177
+ };
178
+ readonly composer: ({ device, text, url }: ShareKitComposerInput) => string;
179
+ readonly count: typeof shareKitCountLength;
180
+ readonly hint: "Opens the LINE app if you have it, or LINE on the web, which asks you to sign in.";
181
+ readonly id: "line";
182
+ readonly images: readonly [{
183
+ readonly height: 630;
184
+ readonly id: "landscape";
185
+ readonly width: 1200;
186
+ }];
187
+ readonly label: "LINE";
188
+ readonly shape: "full";
189
+ };
172
190
  export declare const shareKitMastodon: {
173
191
  readonly actions: {
174
- readonly desktop: readonly [];
175
- readonly mobile: readonly ["share-image"];
192
+ readonly desktop: readonly ["open-composer"];
193
+ readonly mobile: readonly ["share-image", "open-composer"];
176
194
  };
195
+ readonly composer: ({ text }: ShareKitComposerInput) => string;
177
196
  readonly count: ShareKitCounter;
178
197
  readonly id: "mastodon";
179
198
  readonly images: readonly [{
@@ -277,7 +296,7 @@ export declare const shareKitX: {
277
296
  readonly limit: 280;
278
297
  readonly shape: "full";
279
298
  };
280
- declare const shareKitInterfaceIconNames: readonly ["close", "more", "qr"];
299
+ declare const shareKitInterfaceIconNames: readonly ["close", "more"];
281
300
  type ShareKitIconName<Id extends string> = (typeof shareKitInterfaceIconNames)[number] | Id;
282
301
  type ShareKitIcons<Id extends string> = Partial<Record<ShareKitIconName<Id>, string>>;
283
302
  type ShareKitIconsOption<Id extends string> = (() => Promise<ShareKitIcons<Id>>) | ShareKitIcons<Id>;
@@ -286,7 +305,6 @@ export declare const shareKitInterfaceIcons: {
286
305
  readonly close: "M6 7.41 7.41 6 12 10.59 16.59 6 18 7.41 13.41 12 18 16.59 16.59 18 12 13.41 7.41 18 6 16.59 10.59 12Z";
287
306
  readonly messages: "M5 4h14a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2ZM5 6v9h14V6ZM7 17v4l4-4Z";
288
307
  readonly more: "M4 12a2 2 0 1 0 4 0a2 2 0 1 0-4 0ZM10 12a2 2 0 1 0 4 0a2 2 0 1 0-4 0ZM16 12a2 2 0 1 0 4 0a2 2 0 1 0-4 0Z";
289
- readonly qr: "M3 3h7v7H3ZM4.5 4.5v4h4v-4ZM5.5 5.5h2v2h-2ZM14 3h7v7h-7ZM15.5 4.5v4h4v-4ZM16.5 5.5h2v2h-2ZM3 14h7v7H3ZM4.5 15.5v4h4v-4ZM5.5 16.5h2v2h-2ZM14 14h2v2h-2ZM18 14h3v2h-3ZM16 16h2v2h-2ZM14 18h2v3h-2ZM18 18h3v3h-3Z";
290
308
  };
291
309
  declare class ShareIconSource {
292
310
  #private;
@@ -321,27 +339,32 @@ declare const shareKitStringDefaults: {
321
339
  readonly assetCopy: "Copy";
322
340
  readonly assetSave: "Save";
323
341
  readonly assetShare: "Share";
324
- readonly captionCopy: "Copy caption";
325
342
  readonly captionOver: "{count} over the limit for {destination}";
326
343
  readonly captionReset: "Reset";
327
- readonly captionTitle: "Caption";
328
344
  readonly close: "Close";
329
345
  readonly copied: "Copied";
330
- readonly copyManual: "Couldn't copy. The caption is selected, so you can copy it yourself.";
346
+ readonly copyManual: "Couldn't copy. The text is selected, so you can copy it yourself.";
347
+ readonly copyText: "Copy text";
348
+ readonly copyTitle: "Copy title";
349
+ readonly countOver: "{count} over";
331
350
  readonly destinationsMore: "More";
332
351
  readonly destinationsTitle: "Post to";
333
352
  readonly error: "Something went wrong. Try saving instead.";
353
+ readonly fieldText: "Text";
354
+ readonly fieldTitle: "Title";
355
+ readonly imagesHint: "Save or copy one, then add it to your post.";
356
+ readonly imagesHintMobile: "Share one straight to an app, or save it.";
334
357
  readonly imagesTitle: "Images";
335
358
  readonly linkCopy: "Copy link";
336
359
  readonly linkTitle: "Link";
337
- readonly primaryCopy: "Copy caption";
338
360
  readonly primaryOpen: "Open {destination}";
361
+ readonly primarySaveImage: "Save image";
339
362
  readonly primaryShareImage: "Share image";
340
363
  readonly primaryShareLink: "Share link";
341
364
  readonly primaryShareText: "Share";
342
365
  readonly qrAlt: "QR code for this page";
343
366
  readonly qrTitle: "Scan to continue on your phone";
344
- readonly qrToggle: "Continue on your phone";
367
+ readonly qrToggle: "Open on phone";
345
368
  readonly retry: "Ready. Tap again to share.";
346
369
  readonly saved: "Saved";
347
370
  readonly saveError: "Couldn't save. Try again.";
@@ -379,10 +402,12 @@ interface ShareKitPayload<Id extends string> {
379
402
  }
380
403
  export declare const shareKitActionEventName = "share-kit:action";
381
404
  type ShareKitAction = 'copy' | 'copy-caption' | 'copy-link' | 'destination' | 'open' | 'open-composer' | 'qr' | 'save' | 'share' | 'share-link' | 'share-text';
405
+ type ShareKitActionOutcome = 'dismissed' | 'error' | 'retry' | 'saved' | 'shared';
382
406
  interface ShareKitActionDetail {
383
407
  action: ShareKitAction;
384
408
  asset?: string;
385
409
  destination: string;
410
+ outcome?: ShareKitActionOutcome;
386
411
  }
387
412
  declare global {
388
413
  interface GlobalEventHandlersEventMap {
@@ -390,4 +415,4 @@ declare global {
390
415
  }
391
416
  }
392
417
  export declare function serializeShareKitPayload(payload: ShareKitPayload<string>): string;
393
- export type { ShareKitAction, ShareKitActionDetail, ShareKitActionKind, ShareKitAsset, ShareKitClassRole, ShareKitComposerInput, ShareKitCounter, ShareKitDestination, ShareKitDestinationIdOf, ShareKitDestinationList, ShareKitDevice, ShareKitElement, ShareKitIconName, ShareKitIcons, ShareKitIconsOption, ShareKitImageFormat, ShareKitImageFormats, ShareKitOptions, ShareKitPayload, ShareKitSettings, ShareKitStringKey, ShareKitStrings };
418
+ export type { ShareKitAction, ShareKitActionDetail, ShareKitActionKind, ShareKitActionOutcome, ShareKitAsset, ShareKitClassRole, ShareKitComposerInput, ShareKitCounter, ShareKitDestination, ShareKitDestinationIdOf, ShareKitDestinationList, ShareKitDevice, ShareKitElement, ShareKitIconName, ShareKitIcons, ShareKitIconsOption, ShareKitImageFormat, ShareKitImageFormats, ShareKitOptions, ShareKitPayload, ShareKitSettings, ShareKitStringKey, ShareKitStrings };