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/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
- /** Accessible name of the trigger. */
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
- /** Accessible name of the trigger. */
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
- payload = normalizePayload(typeof source === "function" ? source() : source);
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
- return run(() => {
894
- throw cause;
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 = getMediaQueryList(query);
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
- }, [query]);
1022
- const getSnapshot = useCallback(() => getMediaQueryList(query)?.matches ?? false, [query]);
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
- role: politeness === "assertive" ? "alert" : "status",
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 === "object" && value.kind === "text") return value.value;
1186
- return null;
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": ariaLabel ?? field.messages.triggerLabel(field.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,