react-smart-copy 1.14.0 → 1.15.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 +76 -2
- package/dist/index.cjs +523 -34
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +145 -1
- package/dist/index.d.ts +145 -1
- package/dist/index.js +523 -35
- package/dist/index.js.map +1 -1
- package/dist/link.cjs +2 -2
- package/dist/link.cjs.map +1 -1
- package/dist/link.js +2 -2
- package/dist/link.js.map +1 -1
- package/dist/markdown.cjs +17 -1
- package/dist/markdown.cjs.map +1 -1
- package/dist/markdown.js +17 -1
- package/dist/markdown.js.map +1 -1
- package/dist/share.cjs +641 -0
- package/dist/share.cjs.map +1 -0
- package/dist/share.d.cts +248 -0
- package/dist/share.d.ts +248 -0
- package/dist/share.js +638 -0
- package/dist/share.js.map +1 -0
- package/package.json +39 -4
package/dist/index.d.cts
CHANGED
|
@@ -1334,5 +1334,149 @@ interface UseDragCopyResult<T extends HTMLElement = HTMLElement> {
|
|
|
1334
1334
|
*/
|
|
1335
1335
|
export declare function useDragCopy<T extends HTMLElement = HTMLElement>(options: UseDragCopyOptions): UseDragCopyResult<T>;
|
|
1336
1336
|
//#endregion
|
|
1337
|
-
|
|
1337
|
+
//#region src/link/url.d.ts
|
|
1338
|
+
interface CleanLinkOptions {
|
|
1339
|
+
/**
|
|
1340
|
+
* Parameters to remove: exact names, names ending in `_` (a prefix, like
|
|
1341
|
+
* `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
|
|
1342
|
+
*/
|
|
1343
|
+
readonly params?: readonly (string | RegExp)[];
|
|
1344
|
+
/** Parameters never removed, even when `params` matches them. */
|
|
1345
|
+
readonly keep?: readonly string[];
|
|
1346
|
+
}
|
|
1347
|
+
interface LinkUrlOptions {
|
|
1348
|
+
/** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
|
|
1349
|
+
readonly base?: string | URL;
|
|
1350
|
+
/** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
|
|
1351
|
+
readonly protocols?: readonly string[];
|
|
1352
|
+
/** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
|
|
1353
|
+
readonly clean?: boolean | CleanLinkOptions;
|
|
1354
|
+
}
|
|
1355
|
+
//#endregion
|
|
1356
|
+
//#region src/share/share.d.ts
|
|
1357
|
+
/** What to share: a link, a message, files, or any mix of them. */
|
|
1358
|
+
interface ShareContent {
|
|
1359
|
+
/** Validated like every link in this package: allowed schemes only, credentials removed. */
|
|
1360
|
+
readonly url?: string | URL;
|
|
1361
|
+
readonly title?: string;
|
|
1362
|
+
/** A message to share alongside (or instead of) the link. */
|
|
1363
|
+
readonly text?: string;
|
|
1364
|
+
/** Files for the share sheet, where the browser can share them (`navigator.canShare({ files })`). Never copied. */
|
|
1365
|
+
readonly files?: readonly File[];
|
|
1366
|
+
}
|
|
1367
|
+
/** The content after validation: what the share sheet or the clipboard receives. */
|
|
1368
|
+
interface ResolvedShare {
|
|
1369
|
+
readonly url: string | null;
|
|
1370
|
+
/** Cleaned of hidden characters; `null` when there is none. */
|
|
1371
|
+
readonly title: string | null;
|
|
1372
|
+
readonly text: string | null;
|
|
1373
|
+
readonly files: readonly File[];
|
|
1374
|
+
}
|
|
1375
|
+
/**
|
|
1376
|
+
* How to share:
|
|
1377
|
+
* - `auto` (default): the share sheet on phones and tablets, where people expect it; copy elsewhere.
|
|
1378
|
+
* - `native`: the share sheet wherever the browser has one (also desktop Safari, Edge and Chrome on Windows and macOS).
|
|
1379
|
+
* - `copy`: always copy.
|
|
1380
|
+
*/
|
|
1381
|
+
type ShareMode = 'auto' | 'native' | 'copy';
|
|
1382
|
+
type ShareMethod = 'native' | 'copy';
|
|
1383
|
+
/** Structural view of what sharing needs from the browser; `window` by default. */
|
|
1384
|
+
interface ShareEnvironment {
|
|
1385
|
+
readonly navigator?: {
|
|
1386
|
+
readonly share?: (data: ShareData) => Promise<void>;
|
|
1387
|
+
readonly canShare?: (data: ShareData) => boolean;
|
|
1388
|
+
};
|
|
1389
|
+
readonly matchMedia?: (query: string) => {
|
|
1390
|
+
readonly matches: boolean;
|
|
1391
|
+
};
|
|
1392
|
+
}
|
|
1393
|
+
interface ShareOptions extends LinkUrlOptions {
|
|
1394
|
+
/** Default `"auto"`. */
|
|
1395
|
+
readonly mode?: ShareMode;
|
|
1396
|
+
/** When the share sheet fails for a reason other than the user closing it, copy instead. Default `true`. */
|
|
1397
|
+
readonly fallback?: boolean;
|
|
1398
|
+
/**
|
|
1399
|
+
* What to copy. Default: a titled link (`linkPayload`) when there is a URL,
|
|
1400
|
+
* otherwise the text. Return a string or any copy payload.
|
|
1401
|
+
*/
|
|
1402
|
+
readonly copy?: (content: ResolvedShare) => CopyInput;
|
|
1403
|
+
/** Default: the browser Clipboard API, as `useCopy` uses. */
|
|
1404
|
+
readonly adapter?: ClipboardAdapter;
|
|
1405
|
+
/** Default: `window`. For tests, webviews and other hosts. */
|
|
1406
|
+
readonly environment?: ShareEnvironment;
|
|
1407
|
+
/** Aborting it stops a copy in progress; the share sheet itself can only be closed by the user. */
|
|
1408
|
+
readonly signal?: AbortSignal;
|
|
1409
|
+
}
|
|
1410
|
+
/**
|
|
1411
|
+
* Why the content was copied rather than shared: `preferred` (the mode chose
|
|
1412
|
+
* copy, as on desktop in `auto`), `unsupported` (no share sheet, or it can't
|
|
1413
|
+
* take this content) or `fallback` (the share sheet failed).
|
|
1414
|
+
*/
|
|
1415
|
+
type CopyReason = 'preferred' | 'unsupported' | 'fallback';
|
|
1416
|
+
/** What `shareOrCopy` resolves to. It never rejects. */
|
|
1417
|
+
type ShareOutcome = {
|
|
1418
|
+
readonly status: 'shared';
|
|
1419
|
+
readonly method: 'native';
|
|
1420
|
+
readonly content: ResolvedShare;
|
|
1421
|
+
} | {
|
|
1422
|
+
readonly status: 'copied';
|
|
1423
|
+
readonly method: 'copy';
|
|
1424
|
+
readonly reason: CopyReason;
|
|
1425
|
+
readonly payload: CopyPayload;
|
|
1426
|
+
readonly content: ResolvedShare;
|
|
1427
|
+
} |
|
|
1428
|
+
/** The user closed the share sheet. Nothing to report. */
|
|
1429
|
+
{
|
|
1430
|
+
readonly status: 'cancelled';
|
|
1431
|
+
readonly method: 'native';
|
|
1432
|
+
} | {
|
|
1433
|
+
readonly status: 'error';
|
|
1434
|
+
readonly method: ShareMethod;
|
|
1435
|
+
readonly error: CopyError;
|
|
1436
|
+
};
|
|
1437
|
+
//#endregion
|
|
1438
|
+
//#region src/react/useShare.d.ts
|
|
1439
|
+
/** `sharing` lasts while the share sheet is open or the copy is being written. */
|
|
1440
|
+
type ShareStatus = 'idle' | 'sharing' | 'shared' | 'copied' | 'error';
|
|
1441
|
+
interface UseShareOptions extends ShareOptions {
|
|
1442
|
+
/** Time in `shared` or `copied` before returning to `idle`. `false` keeps it. Default 2000. */
|
|
1443
|
+
readonly resetAfterMs?: number | false;
|
|
1444
|
+
/** Called with every settled outcome, including `cancelled`. */
|
|
1445
|
+
readonly onShare?: (outcome: ShareOutcome) => void;
|
|
1446
|
+
}
|
|
1447
|
+
/** What `share()` resolves to: the outcome, or `ignored` while a share is already open. */
|
|
1448
|
+
type UseShareOutcome = ShareOutcome | {
|
|
1449
|
+
readonly status: 'ignored';
|
|
1450
|
+
readonly reason: 'in-flight';
|
|
1451
|
+
};
|
|
1452
|
+
interface UseShareResult {
|
|
1453
|
+
readonly status: ShareStatus;
|
|
1454
|
+
readonly error: CopyError | null;
|
|
1455
|
+
/** The last settled outcome; `null` before the first and after `reset()`. */
|
|
1456
|
+
readonly outcome: ShareOutcome | null;
|
|
1457
|
+
/**
|
|
1458
|
+
* How `share()` will share: `"native"` (the share sheet) or `"copy"`. Label the
|
|
1459
|
+
* button with it ("Share…" or "Copy link"). `"copy"` during server rendering
|
|
1460
|
+
* and hydration, then updated in the browser, also when the device changes.
|
|
1461
|
+
*/
|
|
1462
|
+
readonly method: ShareMethod;
|
|
1463
|
+
/** Stable identity. Call it in a click handler. Never rejects. */
|
|
1464
|
+
readonly share: (content: ShareContent) => Promise<UseShareOutcome>;
|
|
1465
|
+
/** Stable identity. Back to `idle`; the result of a share still open is ignored. */
|
|
1466
|
+
readonly reset: () => void;
|
|
1467
|
+
}
|
|
1468
|
+
/**
|
|
1469
|
+
* Share with the device's share sheet on phones and tablets, and copy a titled
|
|
1470
|
+
* link everywhere else, with honest state for the button. Options may change on
|
|
1471
|
+
* every render; the latest ones are always used.
|
|
1472
|
+
*
|
|
1473
|
+
* @example
|
|
1474
|
+
* const { share, status, method } = useShare();
|
|
1475
|
+
* <button onClick={() => share({ url, title })}>
|
|
1476
|
+
* {status === 'copied' ? 'Link copied' : method === 'native' ? 'Share…' : 'Copy link'}
|
|
1477
|
+
* </button>
|
|
1478
|
+
*/
|
|
1479
|
+
export declare function useShare(options?: UseShareOptions): UseShareResult;
|
|
1480
|
+
//#endregion
|
|
1481
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, CopyReason, DataTransferItemLike, LiveRegionProps, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteDropTargetProps, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldPreviewProps, PasteFieldPreviewRenderProps, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, ResolvedShare, RevealReason, RevealTargetProps, ShareContent, ShareEnvironment, ShareMethod, ShareMode, ShareOptions, ShareOutcome, ShareStatus, UseCopyInterceptorOptions, UseCopyInterceptorResult, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UseDragCopyOptions, UseDragCopyResult, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult, UseShareOptions, UseShareOutcome, UseShareResult };
|
|
1338
1482
|
//# sourceMappingURL=index.d.cts.map
|
package/dist/index.d.ts
CHANGED
|
@@ -1334,5 +1334,149 @@ interface UseDragCopyResult<T extends HTMLElement = HTMLElement> {
|
|
|
1334
1334
|
*/
|
|
1335
1335
|
export declare function useDragCopy<T extends HTMLElement = HTMLElement>(options: UseDragCopyOptions): UseDragCopyResult<T>;
|
|
1336
1336
|
//#endregion
|
|
1337
|
-
|
|
1337
|
+
//#region src/link/url.d.ts
|
|
1338
|
+
interface CleanLinkOptions {
|
|
1339
|
+
/**
|
|
1340
|
+
* Parameters to remove: exact names, names ending in `_` (a prefix, like
|
|
1341
|
+
* `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
|
|
1342
|
+
*/
|
|
1343
|
+
readonly params?: readonly (string | RegExp)[];
|
|
1344
|
+
/** Parameters never removed, even when `params` matches them. */
|
|
1345
|
+
readonly keep?: readonly string[];
|
|
1346
|
+
}
|
|
1347
|
+
interface LinkUrlOptions {
|
|
1348
|
+
/** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
|
|
1349
|
+
readonly base?: string | URL;
|
|
1350
|
+
/** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
|
|
1351
|
+
readonly protocols?: readonly string[];
|
|
1352
|
+
/** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
|
|
1353
|
+
readonly clean?: boolean | CleanLinkOptions;
|
|
1354
|
+
}
|
|
1355
|
+
//#endregion
|
|
1356
|
+
//#region src/share/share.d.ts
|
|
1357
|
+
/** What to share: a link, a message, files, or any mix of them. */
|
|
1358
|
+
interface ShareContent {
|
|
1359
|
+
/** Validated like every link in this package: allowed schemes only, credentials removed. */
|
|
1360
|
+
readonly url?: string | URL;
|
|
1361
|
+
readonly title?: string;
|
|
1362
|
+
/** A message to share alongside (or instead of) the link. */
|
|
1363
|
+
readonly text?: string;
|
|
1364
|
+
/** Files for the share sheet, where the browser can share them (`navigator.canShare({ files })`). Never copied. */
|
|
1365
|
+
readonly files?: readonly File[];
|
|
1366
|
+
}
|
|
1367
|
+
/** The content after validation: what the share sheet or the clipboard receives. */
|
|
1368
|
+
interface ResolvedShare {
|
|
1369
|
+
readonly url: string | null;
|
|
1370
|
+
/** Cleaned of hidden characters; `null` when there is none. */
|
|
1371
|
+
readonly title: string | null;
|
|
1372
|
+
readonly text: string | null;
|
|
1373
|
+
readonly files: readonly File[];
|
|
1374
|
+
}
|
|
1375
|
+
/**
|
|
1376
|
+
* How to share:
|
|
1377
|
+
* - `auto` (default): the share sheet on phones and tablets, where people expect it; copy elsewhere.
|
|
1378
|
+
* - `native`: the share sheet wherever the browser has one (also desktop Safari, Edge and Chrome on Windows and macOS).
|
|
1379
|
+
* - `copy`: always copy.
|
|
1380
|
+
*/
|
|
1381
|
+
type ShareMode = 'auto' | 'native' | 'copy';
|
|
1382
|
+
type ShareMethod = 'native' | 'copy';
|
|
1383
|
+
/** Structural view of what sharing needs from the browser; `window` by default. */
|
|
1384
|
+
interface ShareEnvironment {
|
|
1385
|
+
readonly navigator?: {
|
|
1386
|
+
readonly share?: (data: ShareData) => Promise<void>;
|
|
1387
|
+
readonly canShare?: (data: ShareData) => boolean;
|
|
1388
|
+
};
|
|
1389
|
+
readonly matchMedia?: (query: string) => {
|
|
1390
|
+
readonly matches: boolean;
|
|
1391
|
+
};
|
|
1392
|
+
}
|
|
1393
|
+
interface ShareOptions extends LinkUrlOptions {
|
|
1394
|
+
/** Default `"auto"`. */
|
|
1395
|
+
readonly mode?: ShareMode;
|
|
1396
|
+
/** When the share sheet fails for a reason other than the user closing it, copy instead. Default `true`. */
|
|
1397
|
+
readonly fallback?: boolean;
|
|
1398
|
+
/**
|
|
1399
|
+
* What to copy. Default: a titled link (`linkPayload`) when there is a URL,
|
|
1400
|
+
* otherwise the text. Return a string or any copy payload.
|
|
1401
|
+
*/
|
|
1402
|
+
readonly copy?: (content: ResolvedShare) => CopyInput;
|
|
1403
|
+
/** Default: the browser Clipboard API, as `useCopy` uses. */
|
|
1404
|
+
readonly adapter?: ClipboardAdapter;
|
|
1405
|
+
/** Default: `window`. For tests, webviews and other hosts. */
|
|
1406
|
+
readonly environment?: ShareEnvironment;
|
|
1407
|
+
/** Aborting it stops a copy in progress; the share sheet itself can only be closed by the user. */
|
|
1408
|
+
readonly signal?: AbortSignal;
|
|
1409
|
+
}
|
|
1410
|
+
/**
|
|
1411
|
+
* Why the content was copied rather than shared: `preferred` (the mode chose
|
|
1412
|
+
* copy, as on desktop in `auto`), `unsupported` (no share sheet, or it can't
|
|
1413
|
+
* take this content) or `fallback` (the share sheet failed).
|
|
1414
|
+
*/
|
|
1415
|
+
type CopyReason = 'preferred' | 'unsupported' | 'fallback';
|
|
1416
|
+
/** What `shareOrCopy` resolves to. It never rejects. */
|
|
1417
|
+
type ShareOutcome = {
|
|
1418
|
+
readonly status: 'shared';
|
|
1419
|
+
readonly method: 'native';
|
|
1420
|
+
readonly content: ResolvedShare;
|
|
1421
|
+
} | {
|
|
1422
|
+
readonly status: 'copied';
|
|
1423
|
+
readonly method: 'copy';
|
|
1424
|
+
readonly reason: CopyReason;
|
|
1425
|
+
readonly payload: CopyPayload;
|
|
1426
|
+
readonly content: ResolvedShare;
|
|
1427
|
+
} |
|
|
1428
|
+
/** The user closed the share sheet. Nothing to report. */
|
|
1429
|
+
{
|
|
1430
|
+
readonly status: 'cancelled';
|
|
1431
|
+
readonly method: 'native';
|
|
1432
|
+
} | {
|
|
1433
|
+
readonly status: 'error';
|
|
1434
|
+
readonly method: ShareMethod;
|
|
1435
|
+
readonly error: CopyError;
|
|
1436
|
+
};
|
|
1437
|
+
//#endregion
|
|
1438
|
+
//#region src/react/useShare.d.ts
|
|
1439
|
+
/** `sharing` lasts while the share sheet is open or the copy is being written. */
|
|
1440
|
+
type ShareStatus = 'idle' | 'sharing' | 'shared' | 'copied' | 'error';
|
|
1441
|
+
interface UseShareOptions extends ShareOptions {
|
|
1442
|
+
/** Time in `shared` or `copied` before returning to `idle`. `false` keeps it. Default 2000. */
|
|
1443
|
+
readonly resetAfterMs?: number | false;
|
|
1444
|
+
/** Called with every settled outcome, including `cancelled`. */
|
|
1445
|
+
readonly onShare?: (outcome: ShareOutcome) => void;
|
|
1446
|
+
}
|
|
1447
|
+
/** What `share()` resolves to: the outcome, or `ignored` while a share is already open. */
|
|
1448
|
+
type UseShareOutcome = ShareOutcome | {
|
|
1449
|
+
readonly status: 'ignored';
|
|
1450
|
+
readonly reason: 'in-flight';
|
|
1451
|
+
};
|
|
1452
|
+
interface UseShareResult {
|
|
1453
|
+
readonly status: ShareStatus;
|
|
1454
|
+
readonly error: CopyError | null;
|
|
1455
|
+
/** The last settled outcome; `null` before the first and after `reset()`. */
|
|
1456
|
+
readonly outcome: ShareOutcome | null;
|
|
1457
|
+
/**
|
|
1458
|
+
* How `share()` will share: `"native"` (the share sheet) or `"copy"`. Label the
|
|
1459
|
+
* button with it ("Share…" or "Copy link"). `"copy"` during server rendering
|
|
1460
|
+
* and hydration, then updated in the browser, also when the device changes.
|
|
1461
|
+
*/
|
|
1462
|
+
readonly method: ShareMethod;
|
|
1463
|
+
/** Stable identity. Call it in a click handler. Never rejects. */
|
|
1464
|
+
readonly share: (content: ShareContent) => Promise<UseShareOutcome>;
|
|
1465
|
+
/** Stable identity. Back to `idle`; the result of a share still open is ignored. */
|
|
1466
|
+
readonly reset: () => void;
|
|
1467
|
+
}
|
|
1468
|
+
/**
|
|
1469
|
+
* Share with the device's share sheet on phones and tablets, and copy a titled
|
|
1470
|
+
* link everywhere else, with honest state for the button. Options may change on
|
|
1471
|
+
* every render; the latest ones are always used.
|
|
1472
|
+
*
|
|
1473
|
+
* @example
|
|
1474
|
+
* const { share, status, method } = useShare();
|
|
1475
|
+
* <button onClick={() => share({ url, title })}>
|
|
1476
|
+
* {status === 'copied' ? 'Link copied' : method === 'native' ? 'Share…' : 'Copy link'}
|
|
1477
|
+
* </button>
|
|
1478
|
+
*/
|
|
1479
|
+
export declare function useShare(options?: UseShareOptions): UseShareResult;
|
|
1480
|
+
//#endregion
|
|
1481
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, CopyReason, DataTransferItemLike, LiveRegionProps, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteDropTargetProps, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldPreviewProps, PasteFieldPreviewRenderProps, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, ResolvedShare, RevealReason, RevealTargetProps, ShareContent, ShareEnvironment, ShareMethod, ShareMode, ShareOptions, ShareOutcome, ShareStatus, UseCopyInterceptorOptions, UseCopyInterceptorResult, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UseDragCopyOptions, UseDragCopyResult, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult, UseShareOptions, UseShareOutcome, UseShareResult };
|
|
1338
1482
|
//# sourceMappingURL=index.d.ts.map
|