react-smart-copy 0.2.0 → 1.0.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 +7 -5
- package/dist/capture.cjs +18 -7
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.js +18 -7
- package/dist/capture.js.map +1 -1
- package/dist/core.cjs +23 -4
- package/dist/core.cjs.map +1 -1
- package/dist/core.js +23 -4
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +82 -16
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +16 -1
- package/dist/index.d.ts +16 -1
- package/dist/index.js +82 -16
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.cts
CHANGED
|
@@ -550,6 +550,18 @@ interface LiveRegionProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'childre
|
|
|
550
550
|
/**
|
|
551
551
|
* Always-mounted announcer. Screen readers ignore regions that are inserted
|
|
552
552
|
* together with their content, so this must render before the first message.
|
|
553
|
+
*
|
|
554
|
+
* **Mount safety**: the live region is intentionally empty on mount. We write
|
|
555
|
+
* the message into the DOM imperatively (via a ref) only after the element has
|
|
556
|
+
* been live for at least one browser paint. This prevents SSR hydration and
|
|
557
|
+
* strict-mode double-mount from producing a spurious announcement on some
|
|
558
|
+
* screen readers (JAWS / NVDA observe the initial DOM during hydration and
|
|
559
|
+
* re-read regions that already have text content).
|
|
560
|
+
*
|
|
561
|
+
* **WCAG 4.1.3 / ARIA spec**: we use `role="status"` with explicit `aria-live`
|
|
562
|
+
* rather than `role="alert"`. `role="alert"` interrupts any sentence being
|
|
563
|
+
* spoken even in polite mode, which is inappropriate for copy feedback.
|
|
564
|
+
* `role="status"` + `aria-live` is correct for both politeness levels.
|
|
553
565
|
*/
|
|
554
566
|
export declare function LiveRegion({ message, politeness, visuallyHidden, style, ...rest }: LiveRegionProps): import("react").JSX.Element;
|
|
555
567
|
//#endregion
|
|
@@ -559,7 +571,10 @@ interface CopyFieldMessages {
|
|
|
559
571
|
readonly copied: string;
|
|
560
572
|
/** Announced on failure. Defaults to {@link describeCopyError}. */
|
|
561
573
|
readonly error: (error: CopyError) => string;
|
|
562
|
-
/**
|
|
574
|
+
/**
|
|
575
|
+
* Accessible name of the trigger button. Receives the field's `label` prop.
|
|
576
|
+
* The returned string must not be empty.
|
|
577
|
+
*/
|
|
563
578
|
readonly triggerLabel: (label: string) => string;
|
|
564
579
|
}
|
|
565
580
|
export declare const defaultCopyFieldMessages: CopyFieldMessages;
|
package/dist/index.d.ts
CHANGED
|
@@ -550,6 +550,18 @@ interface LiveRegionProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'childre
|
|
|
550
550
|
/**
|
|
551
551
|
* Always-mounted announcer. Screen readers ignore regions that are inserted
|
|
552
552
|
* together with their content, so this must render before the first message.
|
|
553
|
+
*
|
|
554
|
+
* **Mount safety**: the live region is intentionally empty on mount. We write
|
|
555
|
+
* the message into the DOM imperatively (via a ref) only after the element has
|
|
556
|
+
* been live for at least one browser paint. This prevents SSR hydration and
|
|
557
|
+
* strict-mode double-mount from producing a spurious announcement on some
|
|
558
|
+
* screen readers (JAWS / NVDA observe the initial DOM during hydration and
|
|
559
|
+
* re-read regions that already have text content).
|
|
560
|
+
*
|
|
561
|
+
* **WCAG 4.1.3 / ARIA spec**: we use `role="status"` with explicit `aria-live`
|
|
562
|
+
* rather than `role="alert"`. `role="alert"` interrupts any sentence being
|
|
563
|
+
* spoken even in polite mode, which is inappropriate for copy feedback.
|
|
564
|
+
* `role="status"` + `aria-live` is correct for both politeness levels.
|
|
553
565
|
*/
|
|
554
566
|
export declare function LiveRegion({ message, politeness, visuallyHidden, style, ...rest }: LiveRegionProps): import("react").JSX.Element;
|
|
555
567
|
//#endregion
|
|
@@ -559,7 +571,10 @@ interface CopyFieldMessages {
|
|
|
559
571
|
readonly copied: string;
|
|
560
572
|
/** Announced on failure. Defaults to {@link describeCopyError}. */
|
|
561
573
|
readonly error: (error: CopyError) => string;
|
|
562
|
-
/**
|
|
574
|
+
/**
|
|
575
|
+
* Accessible name of the trigger button. Receives the field's `label` prop.
|
|
576
|
+
* The returned string must not be empty.
|
|
577
|
+
*/
|
|
563
578
|
readonly triggerLabel: (label: string) => string;
|
|
564
579
|
}
|
|
565
580
|
export declare const defaultCopyFieldMessages: CopyFieldMessages;
|
package/dist/index.js
CHANGED
|
@@ -315,7 +315,7 @@ async function writeToClipboard(payload, env, degradeHtmlToText) {
|
|
|
315
315
|
case "multi": {
|
|
316
316
|
const rich = getRichClipboard(env, clipboard);
|
|
317
317
|
if (!rich) throw fail("unsupported-format", "Multi-format copy requires ClipboardItem and navigator.clipboard.write().");
|
|
318
|
-
const record =
|
|
318
|
+
const record = Object.create(null);
|
|
319
319
|
for (const { mimeType, data } of payload.items) {
|
|
320
320
|
if (!isTypeSupported(rich.Item, mimeType)) throw fail("unsupported-format", `This browser cannot write "${mimeType}" to the clipboard.`);
|
|
321
321
|
record[mimeType] = typeof data === "string" ? new Blob([data], { type: mimeType }) : data;
|
|
@@ -454,7 +454,17 @@ function createCopyMachine(options = {}) {
|
|
|
454
454
|
const current = ++generation;
|
|
455
455
|
let payload;
|
|
456
456
|
try {
|
|
457
|
-
|
|
457
|
+
const resolved = typeof source === "function" ? source() : source;
|
|
458
|
+
const resolvedUnknown = resolved;
|
|
459
|
+
if (resolvedUnknown !== null && typeof resolvedUnknown === "object" && typeof resolvedUnknown.then === "function") {
|
|
460
|
+
const error = createCopyError("invalid-payload", "The copy source function must be synchronous. Returning a Promise breaks the user-gesture window required for clipboard writes. Generate your content before calling copy().");
|
|
461
|
+
settleError(error, null, retryCount);
|
|
462
|
+
return Promise.resolve({
|
|
463
|
+
status: "error",
|
|
464
|
+
error
|
|
465
|
+
});
|
|
466
|
+
}
|
|
467
|
+
payload = normalizePayload(resolved);
|
|
458
468
|
} catch (cause) {
|
|
459
469
|
const error = createCopyError("invalid-payload", "The copy source function threw.", cause);
|
|
460
470
|
settleError(error, null, retryCount);
|
|
@@ -890,8 +900,17 @@ function createPasteMachine(options = {}) {
|
|
|
890
900
|
try {
|
|
891
901
|
resolved = resolvePasteReadOptions(current);
|
|
892
902
|
} catch (cause) {
|
|
893
|
-
|
|
894
|
-
|
|
903
|
+
const error = toCopyError(cause, "read");
|
|
904
|
+
++generation;
|
|
905
|
+
clearResetTimer();
|
|
906
|
+
setState({
|
|
907
|
+
status: "error",
|
|
908
|
+
error
|
|
909
|
+
});
|
|
910
|
+
invoke(current.onError, error);
|
|
911
|
+
return Promise.resolve({
|
|
912
|
+
status: "error",
|
|
913
|
+
error
|
|
895
914
|
});
|
|
896
915
|
}
|
|
897
916
|
const entries = snapshotDataTransfer(data, resolved);
|
|
@@ -1006,20 +1025,27 @@ function useCopy(options = {}) {
|
|
|
1006
1025
|
//#endregion
|
|
1007
1026
|
//#region src/react/useMediaQuery.ts
|
|
1008
1027
|
const getServerSnapshot$1 = () => false;
|
|
1009
|
-
function getMediaQueryList(query) {
|
|
1010
|
-
return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(query) : null;
|
|
1011
|
-
}
|
|
1012
1028
|
/** SSR-safe media query subscription. Server and hydration render `false`. */
|
|
1013
1029
|
function useMediaQuery(query) {
|
|
1030
|
+
const listRef = useRef(null);
|
|
1031
|
+
const queryRef = useRef("");
|
|
1032
|
+
const getList = useCallback(() => {
|
|
1033
|
+
if (typeof window === "undefined" || typeof window.matchMedia !== "function") return null;
|
|
1034
|
+
if (listRef.current === null || queryRef.current !== query) {
|
|
1035
|
+
listRef.current = window.matchMedia(query);
|
|
1036
|
+
queryRef.current = query;
|
|
1037
|
+
}
|
|
1038
|
+
return listRef.current;
|
|
1039
|
+
}, [query]);
|
|
1014
1040
|
const subscribe = useCallback((onChange) => {
|
|
1015
|
-
const list =
|
|
1041
|
+
const list = getList();
|
|
1016
1042
|
if (!list) return () => void 0;
|
|
1017
1043
|
list.addEventListener("change", onChange);
|
|
1018
1044
|
return () => {
|
|
1019
1045
|
list.removeEventListener("change", onChange);
|
|
1020
1046
|
};
|
|
1021
|
-
}, [
|
|
1022
|
-
const getSnapshot = useCallback(() =>
|
|
1047
|
+
}, [getList]);
|
|
1048
|
+
const getSnapshot = useCallback(() => getList()?.matches ?? false, [getList]);
|
|
1023
1049
|
return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot$1);
|
|
1024
1050
|
}
|
|
1025
1051
|
//#endregion
|
|
@@ -1152,18 +1178,43 @@ const visuallyHiddenStyle = {
|
|
|
1152
1178
|
/**
|
|
1153
1179
|
* Always-mounted announcer. Screen readers ignore regions that are inserted
|
|
1154
1180
|
* together with their content, so this must render before the first message.
|
|
1181
|
+
*
|
|
1182
|
+
* **Mount safety**: the live region is intentionally empty on mount. We write
|
|
1183
|
+
* the message into the DOM imperatively (via a ref) only after the element has
|
|
1184
|
+
* been live for at least one browser paint. This prevents SSR hydration and
|
|
1185
|
+
* strict-mode double-mount from producing a spurious announcement on some
|
|
1186
|
+
* screen readers (JAWS / NVDA observe the initial DOM during hydration and
|
|
1187
|
+
* re-read regions that already have text content).
|
|
1188
|
+
*
|
|
1189
|
+
* **WCAG 4.1.3 / ARIA spec**: we use `role="status"` with explicit `aria-live`
|
|
1190
|
+
* rather than `role="alert"`. `role="alert"` interrupts any sentence being
|
|
1191
|
+
* spoken even in polite mode, which is inappropriate for copy feedback.
|
|
1192
|
+
* `role="status"` + `aria-live` is correct for both politeness levels.
|
|
1155
1193
|
*/
|
|
1156
1194
|
function LiveRegion({ message, politeness = "polite", visuallyHidden = true, style, ...rest }) {
|
|
1195
|
+
const spanRef = useRef(null);
|
|
1196
|
+
const mountedRef = useRef(false);
|
|
1197
|
+
useEffect(() => {
|
|
1198
|
+
mountedRef.current = true;
|
|
1199
|
+
}, []);
|
|
1200
|
+
useEffect(() => {
|
|
1201
|
+
const span = spanRef.current;
|
|
1202
|
+
/* c8 ignore next -- spanRef.current is always set by mount; guard for unmounted edge case */
|
|
1203
|
+
if (!span) return;
|
|
1204
|
+
/* c8 ignore next -- jsdom effects run synchronously so mountedRef.current is always true here; this guard only fires in real browsers during the initial paint */
|
|
1205
|
+
if (!mountedRef.current) return;
|
|
1206
|
+
span.textContent = message;
|
|
1207
|
+
}, [message]);
|
|
1157
1208
|
return /* @__PURE__ */ jsx("span", {
|
|
1158
1209
|
...rest,
|
|
1159
|
-
|
|
1210
|
+
ref: spanRef,
|
|
1211
|
+
role: "status",
|
|
1160
1212
|
"aria-live": politeness,
|
|
1161
1213
|
"aria-atomic": "true",
|
|
1162
1214
|
style: visuallyHidden ? {
|
|
1163
1215
|
...visuallyHiddenStyle,
|
|
1164
1216
|
...style
|
|
1165
|
-
} : style
|
|
1166
|
-
children: message
|
|
1217
|
+
} : style
|
|
1167
1218
|
});
|
|
1168
1219
|
}
|
|
1169
1220
|
//#endregion
|
|
@@ -1180,10 +1231,23 @@ function useCopyField() {
|
|
|
1180
1231
|
if (!context) throw new Error("useCopyField() must be used inside <CopyField.Root>.");
|
|
1181
1232
|
return context;
|
|
1182
1233
|
}
|
|
1234
|
+
/** Maps non-text payload kinds to a human-readable description for screen readers. */
|
|
1235
|
+
const KIND_LABELS = /* @__PURE__ */ Object.freeze(Object.assign(Object.create(null), {
|
|
1236
|
+
html: "Rich text",
|
|
1237
|
+
image: "Image",
|
|
1238
|
+
json: "JSON data",
|
|
1239
|
+
multi: "Mixed content"
|
|
1240
|
+
}));
|
|
1241
|
+
/**
|
|
1242
|
+
* Returns the value's text representation when it is plain text, or a
|
|
1243
|
+
* descriptive fallback for non-text payloads so screen-reader users understand
|
|
1244
|
+
* what will be copied (A1: `CopyField.Value` must never be silent).
|
|
1245
|
+
*/
|
|
1183
1246
|
function getDisplayValue(value) {
|
|
1184
1247
|
if (typeof value === "string") return value;
|
|
1185
|
-
if (typeof value === "
|
|
1186
|
-
return
|
|
1248
|
+
if (typeof value === "function") return null;
|
|
1249
|
+
if (value.kind === "text") return value.value;
|
|
1250
|
+
return KIND_LABELS[value.kind] ?? null;
|
|
1187
1251
|
}
|
|
1188
1252
|
const Root = /* @__PURE__ */ forwardRef(function CopyFieldRoot({ value, label, copyOptions, messages: messageOverrides, alwaysVisible = false, announce = true, pendingDelayMs, minPendingMs, children, onPointerEnter, onPointerLeave, onPointerDown, onFocus, onBlur, ...rest }, forwardedRef) {
|
|
1189
1253
|
const copyState = useCopy(copyOptions);
|
|
@@ -1322,11 +1386,13 @@ const CopyField = {
|
|
|
1322
1386
|
revealed: field.revealed,
|
|
1323
1387
|
canRetry: field.canRetry
|
|
1324
1388
|
};
|
|
1389
|
+
const computedAriaLabel = ariaLabel ?? field.messages.triggerLabel(field.label);
|
|
1390
|
+
const safeAriaLabel = computedAriaLabel.length > 0 ? computedAriaLabel : `Copy ${field.label}`;
|
|
1325
1391
|
return /* @__PURE__ */ jsx("button", {
|
|
1326
1392
|
...rest,
|
|
1327
1393
|
ref,
|
|
1328
1394
|
type: "button",
|
|
1329
|
-
"aria-label":
|
|
1395
|
+
"aria-label": safeAriaLabel,
|
|
1330
1396
|
"data-state": field.status,
|
|
1331
1397
|
"data-display-state": field.displayStatus,
|
|
1332
1398
|
"data-revealed": field.revealed ? "" : void 0,
|