react-smart-copy 1.0.0 → 1.1.1

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
@@ -255,7 +255,10 @@ export interface CopyMachineOptions {
255
255
  readonly adapter?: ClipboardAdapter;
256
256
  /** Time in `copied` before returning to `idle`. `false`/`Infinity` disables. Default 2000. */
257
257
  readonly resetAfterMs?: number | false;
258
- /** Max `retry()` calls after the first failure. Default 3. */
258
+ /**
259
+ * Max `retry()` calls after the first failure. Default 3. `0` disables
260
+ * retry; `Infinity` allows unlimited retries.
261
+ */
259
262
  readonly maxRetries?: number;
260
263
  /**
261
264
  * Share "Copied" with other machines: only one member of a coordinator
@@ -690,5 +693,115 @@ export declare function CopyGroup({ children, coordinator }: CopyGroupProps): im
690
693
  /** The nearest `<CopyGroup>`'s coordinator, or `null` outside any group. */
691
694
  export declare function useCopyGroup(): CopyCoordinator | null;
692
695
  //#endregion
693
- export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
696
+ //#region src/react/usePasteDisplayStatus.d.ts
697
+ export declare const DEFAULT_PASTE_PENDING_DELAY_MS = 150;
698
+ export declare const DEFAULT_PASTE_MIN_PENDING_MS = 400;
699
+ interface UsePasteDisplayStatusOptions {
700
+ /** Only show `reading` if the paste takes longer than this. Default 150 ms. */
701
+ readonly pendingDelayMs?: number;
702
+ /** Once `reading` is shown, keep it visible at least this long. Default 400 ms. */
703
+ readonly minPendingMs?: number;
704
+ }
705
+ /**
706
+ * Presentation-only view of a paste status that never flickers.
707
+ *
708
+ * The real `status` is honest and can be `reading` for a single render frame
709
+ * (plain-text reads take ~1-5 ms). Rendering that directly flashes a "Reading…"
710
+ * label. This hook keeps showing the previous settled status during fast pastes,
711
+ * and when a paste is genuinely slow it shows `reading` for a minimum time
712
+ * instead of a blink.
713
+ *
714
+ * It never changes the state machine: use `status` for logic, this for pixels.
715
+ */
716
+ export declare function usePasteDisplayStatus(status: PasteStatus, options?: UsePasteDisplayStatusOptions): PasteStatus;
717
+ //#endregion
718
+ //#region src/react/PasteField.d.ts
719
+ interface PasteFieldMessages {
720
+ /** Announced to screen readers on successful paste. */
721
+ readonly pasted: string | ((result: PasteResult) => string);
722
+ /** Announced on failure. Defaults to {@link describePasteError}. */
723
+ readonly error: (error: CopyError) => string;
724
+ /**
725
+ * Accessible name of the trigger button. Receives the field's `label` prop.
726
+ * The returned string must not be empty.
727
+ */
728
+ readonly triggerLabel: (label: string) => string;
729
+ /**
730
+ * Accessible name of the drop zone / paste target area.
731
+ * Receives the field's `label` prop.
732
+ */
733
+ readonly zoneLabel: (label: string) => string;
734
+ }
735
+ export declare const defaultPasteFieldMessages: PasteFieldMessages;
736
+ interface PasteFieldContextValue extends UsePasteResult {
737
+ readonly label: string;
738
+ readonly labelId: string;
739
+ readonly zoneId: string;
740
+ readonly revealed: boolean;
741
+ readonly revealReason: RevealReason | null;
742
+ readonly messages: PasteFieldMessages;
743
+ /** Flicker-free status for rendering. Use `status` for logic, this for pixels. */
744
+ readonly displayStatus: PasteStatus;
745
+ /** Triggers a programmatic paste (via Clipboard API, may prompt for permission). */
746
+ readonly doPaste: () => Promise<PasteOutcome>;
747
+ }
748
+ /** Access field state to build custom parts. Must be used inside `<PasteField.Root>`. */
749
+ export declare function usePasteField(): PasteFieldContextValue;
750
+ interface PasteFieldRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPaste' | 'onError'>, UsePasteDisplayStatusOptions {
751
+ /** Human label — used for the trigger's and zone's accessible names. */
752
+ readonly label: string;
753
+ readonly pasteOptions?: UsePasteOptions;
754
+ readonly messages?: Partial<PasteFieldMessages>;
755
+ /** Skip hover/focus reveal and always show the trigger. */
756
+ readonly alwaysVisible?: boolean;
757
+ /** Render the built-in live region. Disable if your app has a global announcer. Default `true`. */
758
+ readonly announce?: boolean;
759
+ }
760
+ type PasteFieldLabelProps = HTMLAttributes<HTMLSpanElement>;
761
+ interface PasteFieldStatusProps extends HTMLAttributes<HTMLSpanElement> {
762
+ /** Map each paste status to a label. Defaults to English strings. */
763
+ readonly labels?: Partial<Readonly<Record<PasteStatus, string>>>;
764
+ }
765
+ interface PasteFieldZoneProps extends HTMLAttributes<HTMLDivElement> {
766
+ /** When true, the zone is always focusable (tabIndex=0). Default true. */
767
+ readonly focusable?: boolean;
768
+ }
769
+ interface PasteFieldTriggerRenderProps {
770
+ /** The real state. Use for logic. */
771
+ readonly status: PasteStatus;
772
+ /** Flicker-free state. Use for what you render. */
773
+ readonly displayStatus: PasteStatus;
774
+ readonly state: PasteState;
775
+ readonly revealed: boolean;
776
+ }
777
+ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
778
+ /** Static content, or a render function receiving the live state. */
779
+ readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
780
+ }
781
+ /**
782
+ * Headless compound component for a labelled, paste-ready field.
783
+ *
784
+ * Styling hooks on Root, Zone and Trigger:
785
+ * - `data-display-state="idle|reading|read|error"`: flicker-free, style with this
786
+ * - `data-state`: the real, instantaneous state, for logic and tests
787
+ * - `data-revealed`: present while the trigger should be visible
788
+ *
789
+ * @example
790
+ * ```tsx
791
+ * <PasteField.Root label="Notes">
792
+ * <PasteField.Label />
793
+ * <PasteField.Zone />
794
+ * <PasteField.Trigger />
795
+ * </PasteField.Root>
796
+ * ```
797
+ */
798
+ export declare const PasteField: {
799
+ readonly Root: import("react").ForwardRefExoticComponent<PasteFieldRootProps & import("react").RefAttributes<HTMLDivElement>>;
800
+ readonly Label: import("react").ForwardRefExoticComponent<PasteFieldLabelProps & import("react").RefAttributes<HTMLSpanElement>>;
801
+ readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
802
+ readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
803
+ readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
804
+ };
805
+ //#endregion
806
+ export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
694
807
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.ts CHANGED
@@ -255,7 +255,10 @@ export interface CopyMachineOptions {
255
255
  readonly adapter?: ClipboardAdapter;
256
256
  /** Time in `copied` before returning to `idle`. `false`/`Infinity` disables. Default 2000. */
257
257
  readonly resetAfterMs?: number | false;
258
- /** Max `retry()` calls after the first failure. Default 3. */
258
+ /**
259
+ * Max `retry()` calls after the first failure. Default 3. `0` disables
260
+ * retry; `Infinity` allows unlimited retries.
261
+ */
259
262
  readonly maxRetries?: number;
260
263
  /**
261
264
  * Share "Copied" with other machines: only one member of a coordinator
@@ -690,5 +693,115 @@ export declare function CopyGroup({ children, coordinator }: CopyGroupProps): im
690
693
  /** The nearest `<CopyGroup>`'s coordinator, or `null` outside any group. */
691
694
  export declare function useCopyGroup(): CopyCoordinator | null;
692
695
  //#endregion
693
- export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
696
+ //#region src/react/usePasteDisplayStatus.d.ts
697
+ export declare const DEFAULT_PASTE_PENDING_DELAY_MS = 150;
698
+ export declare const DEFAULT_PASTE_MIN_PENDING_MS = 400;
699
+ interface UsePasteDisplayStatusOptions {
700
+ /** Only show `reading` if the paste takes longer than this. Default 150 ms. */
701
+ readonly pendingDelayMs?: number;
702
+ /** Once `reading` is shown, keep it visible at least this long. Default 400 ms. */
703
+ readonly minPendingMs?: number;
704
+ }
705
+ /**
706
+ * Presentation-only view of a paste status that never flickers.
707
+ *
708
+ * The real `status` is honest and can be `reading` for a single render frame
709
+ * (plain-text reads take ~1-5 ms). Rendering that directly flashes a "Reading…"
710
+ * label. This hook keeps showing the previous settled status during fast pastes,
711
+ * and when a paste is genuinely slow it shows `reading` for a minimum time
712
+ * instead of a blink.
713
+ *
714
+ * It never changes the state machine: use `status` for logic, this for pixels.
715
+ */
716
+ export declare function usePasteDisplayStatus(status: PasteStatus, options?: UsePasteDisplayStatusOptions): PasteStatus;
717
+ //#endregion
718
+ //#region src/react/PasteField.d.ts
719
+ interface PasteFieldMessages {
720
+ /** Announced to screen readers on successful paste. */
721
+ readonly pasted: string | ((result: PasteResult) => string);
722
+ /** Announced on failure. Defaults to {@link describePasteError}. */
723
+ readonly error: (error: CopyError) => string;
724
+ /**
725
+ * Accessible name of the trigger button. Receives the field's `label` prop.
726
+ * The returned string must not be empty.
727
+ */
728
+ readonly triggerLabel: (label: string) => string;
729
+ /**
730
+ * Accessible name of the drop zone / paste target area.
731
+ * Receives the field's `label` prop.
732
+ */
733
+ readonly zoneLabel: (label: string) => string;
734
+ }
735
+ export declare const defaultPasteFieldMessages: PasteFieldMessages;
736
+ interface PasteFieldContextValue extends UsePasteResult {
737
+ readonly label: string;
738
+ readonly labelId: string;
739
+ readonly zoneId: string;
740
+ readonly revealed: boolean;
741
+ readonly revealReason: RevealReason | null;
742
+ readonly messages: PasteFieldMessages;
743
+ /** Flicker-free status for rendering. Use `status` for logic, this for pixels. */
744
+ readonly displayStatus: PasteStatus;
745
+ /** Triggers a programmatic paste (via Clipboard API, may prompt for permission). */
746
+ readonly doPaste: () => Promise<PasteOutcome>;
747
+ }
748
+ /** Access field state to build custom parts. Must be used inside `<PasteField.Root>`. */
749
+ export declare function usePasteField(): PasteFieldContextValue;
750
+ interface PasteFieldRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onPaste' | 'onError'>, UsePasteDisplayStatusOptions {
751
+ /** Human label — used for the trigger's and zone's accessible names. */
752
+ readonly label: string;
753
+ readonly pasteOptions?: UsePasteOptions;
754
+ readonly messages?: Partial<PasteFieldMessages>;
755
+ /** Skip hover/focus reveal and always show the trigger. */
756
+ readonly alwaysVisible?: boolean;
757
+ /** Render the built-in live region. Disable if your app has a global announcer. Default `true`. */
758
+ readonly announce?: boolean;
759
+ }
760
+ type PasteFieldLabelProps = HTMLAttributes<HTMLSpanElement>;
761
+ interface PasteFieldStatusProps extends HTMLAttributes<HTMLSpanElement> {
762
+ /** Map each paste status to a label. Defaults to English strings. */
763
+ readonly labels?: Partial<Readonly<Record<PasteStatus, string>>>;
764
+ }
765
+ interface PasteFieldZoneProps extends HTMLAttributes<HTMLDivElement> {
766
+ /** When true, the zone is always focusable (tabIndex=0). Default true. */
767
+ readonly focusable?: boolean;
768
+ }
769
+ interface PasteFieldTriggerRenderProps {
770
+ /** The real state. Use for logic. */
771
+ readonly status: PasteStatus;
772
+ /** Flicker-free state. Use for what you render. */
773
+ readonly displayStatus: PasteStatus;
774
+ readonly state: PasteState;
775
+ readonly revealed: boolean;
776
+ }
777
+ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
778
+ /** Static content, or a render function receiving the live state. */
779
+ readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
780
+ }
781
+ /**
782
+ * Headless compound component for a labelled, paste-ready field.
783
+ *
784
+ * Styling hooks on Root, Zone and Trigger:
785
+ * - `data-display-state="idle|reading|read|error"`: flicker-free, style with this
786
+ * - `data-state`: the real, instantaneous state, for logic and tests
787
+ * - `data-revealed`: present while the trigger should be visible
788
+ *
789
+ * @example
790
+ * ```tsx
791
+ * <PasteField.Root label="Notes">
792
+ * <PasteField.Label />
793
+ * <PasteField.Zone />
794
+ * <PasteField.Trigger />
795
+ * </PasteField.Root>
796
+ * ```
797
+ */
798
+ export declare const PasteField: {
799
+ readonly Root: import("react").ForwardRefExoticComponent<PasteFieldRootProps & import("react").RefAttributes<HTMLDivElement>>;
800
+ readonly Label: import("react").ForwardRefExoticComponent<PasteFieldLabelProps & import("react").RefAttributes<HTMLSpanElement>>;
801
+ readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
802
+ readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
803
+ readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
804
+ };
805
+ //#endregion
806
+ export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
694
807
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -1218,6 +1218,36 @@ function LiveRegion({ message, politeness = "polite", visuallyHidden = true, sty
1218
1218
  });
1219
1219
  }
1220
1220
  //#endregion
1221
+ //#region src/react/TriggerLabel.tsx
1222
+ /**
1223
+ * Default trigger label shared by `CopyField` and `PasteField`: every state's
1224
+ * text is stacked in one grid cell, so the button is always as wide as its
1225
+ * longest label and never resizes (no layout shift). Only the active label is
1226
+ * visible and exposed to assistive tech; the crossfade is skipped when the
1227
+ * user prefers reduced motion.
1228
+ */
1229
+ function TriggerLabel({ status, labels }) {
1230
+ const reduceMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
1231
+ return /* @__PURE__ */ jsx("span", {
1232
+ style: { display: "inline-grid" },
1233
+ children: Object.keys(labels).map((candidate) => {
1234
+ const active = candidate === status;
1235
+ return /* @__PURE__ */ jsx("span", {
1236
+ "data-trigger-label": candidate,
1237
+ "data-active": active ? "" : void 0,
1238
+ "aria-hidden": !active || void 0,
1239
+ style: {
1240
+ gridArea: "1 / 1",
1241
+ opacity: active ? 1 : 0,
1242
+ visibility: active ? "visible" : "hidden",
1243
+ ...reduceMotion ? {} : { transition: "opacity 150ms ease, visibility 150ms" }
1244
+ },
1245
+ children: labels[candidate]
1246
+ }, candidate);
1247
+ })
1248
+ });
1249
+ }
1250
+ //#endregion
1221
1251
  //#region src/react/CopyField.tsx
1222
1252
  const defaultCopyFieldMessages = {
1223
1253
  copied: "Copied to clipboard",
@@ -1249,7 +1279,7 @@ function getDisplayValue(value) {
1249
1279
  if (value.kind === "text") return value.value;
1250
1280
  return KIND_LABELS[value.kind] ?? null;
1251
1281
  }
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) {
1282
+ const Root$1 = /* @__PURE__ */ forwardRef(function CopyFieldRoot({ value, label, copyOptions, messages: messageOverrides, alwaysVisible = false, announce = true, pendingDelayMs, minPendingMs, children, onPointerEnter, onPointerLeave, onPointerDown, onFocus, onBlur, ...rest }, forwardedRef) {
1253
1283
  const copyState = useCopy(copyOptions);
1254
1284
  const displayStatus = useDisplayStatus(copyState.status, {
1255
1285
  ...pendingDelayMs === void 0 ? {} : { pendingDelayMs },
@@ -1309,7 +1339,7 @@ const Root = /* @__PURE__ */ forwardRef(function CopyFieldRoot({ value, label, c
1309
1339
  })
1310
1340
  });
1311
1341
  });
1312
- const Label = /* @__PURE__ */ forwardRef(function CopyFieldLabel({ children, ...rest }, ref) {
1342
+ const Label$1 = /* @__PURE__ */ forwardRef(function CopyFieldLabel({ children, ...rest }, ref) {
1313
1343
  const field = useCopyField();
1314
1344
  return /* @__PURE__ */ jsx("span", {
1315
1345
  ...rest,
@@ -1327,44 +1357,12 @@ const Value = /* @__PURE__ */ forwardRef(function CopyFieldValue({ children, ...
1327
1357
  children: children ?? field.displayValue
1328
1358
  });
1329
1359
  });
1330
- const DEFAULT_TRIGGER_TEXT = {
1360
+ const DEFAULT_TRIGGER_TEXT$1 = {
1331
1361
  idle: "Copy",
1332
1362
  copying: "Copying…",
1333
1363
  copied: "Copied",
1334
1364
  error: "Retry"
1335
1365
  };
1336
- const TRIGGER_STATUSES = [
1337
- "idle",
1338
- "copying",
1339
- "copied",
1340
- "error"
1341
- ];
1342
- /**
1343
- * Default label: every state's text is stacked in the same grid cell, so the
1344
- * button is always as wide as its longest label and never resizes (no layout
1345
- * shift). Only the active one is visible; the others crossfade out.
1346
- */
1347
- function DefaultTriggerLabel({ status }) {
1348
- const reduceMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
1349
- return /* @__PURE__ */ jsx("span", {
1350
- style: { display: "inline-grid" },
1351
- children: TRIGGER_STATUSES.map((candidate) => {
1352
- const active = candidate === status;
1353
- return /* @__PURE__ */ jsx("span", {
1354
- "data-trigger-label": candidate,
1355
- "data-active": active ? "" : void 0,
1356
- "aria-hidden": active ? void 0 : true,
1357
- style: {
1358
- gridArea: "1 / 1",
1359
- opacity: active ? 1 : 0,
1360
- visibility: active ? "visible" : "hidden",
1361
- ...reduceMotion ? {} : { transition: "opacity 150ms ease, visibility 150ms" }
1362
- },
1363
- children: DEFAULT_TRIGGER_TEXT[candidate]
1364
- }, candidate);
1365
- })
1366
- });
1367
- }
1368
1366
  /**
1369
1367
  * Headless compound component for a labelled, copyable value.
1370
1368
  *
@@ -1374,8 +1372,8 @@ function DefaultTriggerLabel({ status }) {
1374
1372
  * - `data-revealed`: present while the trigger should be visible
1375
1373
  */
1376
1374
  const CopyField = {
1377
- Root,
1378
- Label,
1375
+ Root: Root$1,
1376
+ Label: Label$1,
1379
1377
  Value,
1380
1378
  Trigger: /* @__PURE__ */ forwardRef(function CopyFieldTrigger({ children, onClick, "aria-label": ariaLabel, ...rest }, ref) {
1381
1379
  const field = useCopyField();
@@ -1386,20 +1384,23 @@ const CopyField = {
1386
1384
  revealed: field.revealed,
1387
1385
  canRetry: field.canRetry
1388
1386
  };
1389
- const computedAriaLabel = ariaLabel ?? field.messages.triggerLabel(field.label);
1390
- const safeAriaLabel = computedAriaLabel.length > 0 ? computedAriaLabel : `Copy ${field.label}`;
1387
+ const safeAriaLabel = (ariaLabel ?? field.messages.triggerLabel(field.label)) || defaultCopyFieldMessages.triggerLabel(field.label);
1391
1388
  return /* @__PURE__ */ jsx("button", {
1392
1389
  ...rest,
1393
1390
  ref,
1394
1391
  type: "button",
1395
1392
  "aria-label": safeAriaLabel,
1393
+ "aria-busy": field.status === "copying" ? true : void 0,
1396
1394
  "data-state": field.status,
1397
1395
  "data-display-state": field.displayStatus,
1398
1396
  "data-revealed": field.revealed ? "" : void 0,
1399
1397
  onClick: composeEventHandlers(onClick, () => {
1400
1398
  field.copyValue();
1401
1399
  }),
1402
- children: typeof children === "function" ? children(renderProps) : children ?? /* @__PURE__ */ jsx(DefaultTriggerLabel, { status: field.displayStatus })
1400
+ children: typeof children === "function" ? children(renderProps) : children ?? /* @__PURE__ */ jsx(TriggerLabel, {
1401
+ status: field.displayStatus,
1402
+ labels: DEFAULT_TRIGGER_TEXT$1
1403
+ })
1403
1404
  });
1404
1405
  })
1405
1406
  };
@@ -1451,6 +1452,240 @@ function usePaste(options = {}) {
1451
1452
  ]);
1452
1453
  }
1453
1454
  //#endregion
1454
- export { CopyFailure, CopyField, CopyGroup, DEFAULT_MAX_RETRIES, DEFAULT_MIN_PENDING_MS, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_PENDING_DELAY_MS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, LiveRegion, PASTE_IDLE_STATE, SVG_MIME_TYPE, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, defaultCopyFieldMessages, describeCopyError, describePasteError, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, useCopy, useCopyField, useCopyGroup, useDisplayStatus, usePaste, useRevealOnInteraction, validatePayload, visuallyHiddenStyle };
1455
+ //#region src/react/usePasteDisplayStatus.ts
1456
+ const DEFAULT_PASTE_PENDING_DELAY_MS = 150;
1457
+ const DEFAULT_PASTE_MIN_PENDING_MS = 400;
1458
+ /**
1459
+ * Presentation-only view of a paste status that never flickers.
1460
+ *
1461
+ * The real `status` is honest and can be `reading` for a single render frame
1462
+ * (plain-text reads take ~1-5 ms). Rendering that directly flashes a "Reading…"
1463
+ * label. This hook keeps showing the previous settled status during fast pastes,
1464
+ * and when a paste is genuinely slow it shows `reading` for a minimum time
1465
+ * instead of a blink.
1466
+ *
1467
+ * It never changes the state machine: use `status` for logic, this for pixels.
1468
+ */
1469
+ function usePasteDisplayStatus(status, options = {}) {
1470
+ const pendingDelayMs = Math.max(0, options.pendingDelayMs ?? 150);
1471
+ const minPendingMs = Math.max(0, options.minPendingMs ?? 400);
1472
+ const [settled, setSettled] = useState(status === "reading" ? "idle" : status);
1473
+ useIsomorphicLayoutEffect(() => {
1474
+ if (status !== "reading") setSettled(status);
1475
+ }, [status]);
1476
+ const [pendingShownAt, setPendingShownAt] = useState(null);
1477
+ useEffect(() => {
1478
+ if (status !== "reading") return void 0;
1479
+ const timer = setTimeout(() => {
1480
+ setPendingShownAt(Date.now());
1481
+ }, pendingDelayMs);
1482
+ return () => {
1483
+ clearTimeout(timer);
1484
+ };
1485
+ }, [status, pendingDelayMs]);
1486
+ useEffect(() => {
1487
+ if (status === "reading" || pendingShownAt === null) return void 0;
1488
+ const remaining = Math.max(0, minPendingMs - (Date.now() - pendingShownAt));
1489
+ const timer = setTimeout(() => {
1490
+ setPendingShownAt(null);
1491
+ }, remaining);
1492
+ return () => {
1493
+ clearTimeout(timer);
1494
+ };
1495
+ }, [
1496
+ status,
1497
+ pendingShownAt,
1498
+ minPendingMs
1499
+ ]);
1500
+ if (pendingShownAt !== null) return "reading";
1501
+ return status === "reading" ? settled : status;
1502
+ }
1503
+ //#endregion
1504
+ //#region src/react/PasteField.tsx
1505
+ const defaultPasteFieldMessages = {
1506
+ pasted: "Pasted from clipboard",
1507
+ error: describePasteError,
1508
+ triggerLabel: (label) => `Paste ${label}`,
1509
+ zoneLabel: (label) => `Paste area for ${label}`
1510
+ };
1511
+ const PasteFieldContext = /* @__PURE__ */ createContext(null);
1512
+ /** Access field state to build custom parts. Must be used inside `<PasteField.Root>`. */
1513
+ function usePasteField() {
1514
+ const context = useContext(PasteFieldContext);
1515
+ if (!context) throw new Error("usePasteField() must be used inside <PasteField.Root>.");
1516
+ return context;
1517
+ }
1518
+ const Root = /* @__PURE__ */ forwardRef(function PasteFieldRoot({ label, pasteOptions, messages: messageOverrides, alwaysVisible = false, announce = true, pendingDelayMs, minPendingMs, children, onPointerEnter, onPointerLeave, onPointerDown, onFocus, onBlur, ...rest }, forwardedRef) {
1519
+ const pasteState = usePaste(pasteOptions);
1520
+ const displayStatus = usePasteDisplayStatus(pasteState.status, {
1521
+ ...pendingDelayMs === void 0 ? {} : { pendingDelayMs },
1522
+ ...minPendingMs === void 0 ? {} : { minPendingMs }
1523
+ });
1524
+ const reveal = useRevealOnInteraction({ alwaysVisible });
1525
+ const baseId = useId();
1526
+ const labelId = `${baseId}-label`;
1527
+ const zoneId = `${baseId}-zone`;
1528
+ const messages = useMemo(() => ({
1529
+ ...defaultPasteFieldMessages,
1530
+ ...messageOverrides
1531
+ }), [messageOverrides]);
1532
+ const { paste: machinePaste } = pasteState;
1533
+ const doPaste = useCallback(() => machinePaste(), [machinePaste]);
1534
+ const { targetProps } = reveal;
1535
+ const ref = useMemo(() => mergeRefs(targetProps.ref, forwardedRef), [targetProps.ref, forwardedRef]);
1536
+ const context = useMemo(() => ({
1537
+ ...pasteState,
1538
+ label,
1539
+ labelId,
1540
+ zoneId,
1541
+ revealed: reveal.visible,
1542
+ revealReason: reveal.reason,
1543
+ messages,
1544
+ displayStatus,
1545
+ doPaste
1546
+ }), [
1547
+ pasteState,
1548
+ label,
1549
+ labelId,
1550
+ zoneId,
1551
+ reveal.visible,
1552
+ reveal.reason,
1553
+ messages,
1554
+ displayStatus,
1555
+ doPaste
1556
+ ]);
1557
+ const { state } = pasteState;
1558
+ const announcement = state.status === "read" ? typeof messages.pasted === "function" ? messages.pasted(state.result) : messages.pasted : state.status === "error" ? messages.error(state.error) : "";
1559
+ return /* @__PURE__ */ jsx(PasteFieldContext.Provider, {
1560
+ value: context,
1561
+ children: /* @__PURE__ */ jsxs("div", {
1562
+ ...rest,
1563
+ ref,
1564
+ "data-state": state.status,
1565
+ "data-display-state": displayStatus,
1566
+ "data-revealed": reveal.visible ? "" : void 0,
1567
+ onPointerEnter: composeEventHandlers(onPointerEnter, targetProps.onPointerEnter),
1568
+ onPointerLeave: composeEventHandlers(onPointerLeave, targetProps.onPointerLeave),
1569
+ onPointerDown: composeEventHandlers(onPointerDown, targetProps.onPointerDown),
1570
+ onFocus: composeEventHandlers(onFocus, targetProps.onFocus),
1571
+ onBlur: composeEventHandlers(onBlur, targetProps.onBlur),
1572
+ children: [children, announce ? /* @__PURE__ */ jsx(LiveRegion, { message: announcement }) : null]
1573
+ })
1574
+ });
1575
+ });
1576
+ const Label = /* @__PURE__ */ forwardRef(function PasteFieldLabel({ children, ...rest }, ref) {
1577
+ const field = usePasteField();
1578
+ return /* @__PURE__ */ jsx("span", {
1579
+ ...rest,
1580
+ ref,
1581
+ id: field.labelId,
1582
+ children: children ?? field.label
1583
+ });
1584
+ });
1585
+ const DEFAULT_STATUS_LABELS = {
1586
+ idle: "Ready",
1587
+ reading: "Reading…",
1588
+ read: "Pasted",
1589
+ error: "Error"
1590
+ };
1591
+ const Status = /* @__PURE__ */ forwardRef(function PasteFieldStatus({ children, labels, ...rest }, ref) {
1592
+ const field = usePasteField();
1593
+ const resolved = labels ? {
1594
+ ...DEFAULT_STATUS_LABELS,
1595
+ ...labels
1596
+ } : DEFAULT_STATUS_LABELS;
1597
+ return /* @__PURE__ */ jsx("span", {
1598
+ ...rest,
1599
+ ref,
1600
+ "data-state": field.status,
1601
+ "data-display-state": field.displayStatus,
1602
+ children: children ?? resolved[field.displayStatus]
1603
+ });
1604
+ });
1605
+ /**
1606
+ * A focusable paste target. Accepts keyboard paste (Ctrl/⌘+V) without a
1607
+ * permission prompt and renders `data-zone` for styling.
1608
+ *
1609
+ * Accessible name: `aria-label` prop, else `messages.zoneLabel(label)`
1610
+ * ("Paste area for Notes"). Pass `aria-labelledby` explicitly to name it from
1611
+ * another element instead.
1612
+ */
1613
+ const Zone = /* @__PURE__ */ forwardRef(function PasteFieldZone({ children, focusable = true, onPaste, "aria-label": ariaLabel, tabIndex, ...rest }, ref) {
1614
+ const field = usePasteField();
1615
+ const { targetProps } = field;
1616
+ const safeAriaLabel = (ariaLabel ?? field.messages.zoneLabel(field.label)) || defaultPasteFieldMessages.zoneLabel(field.label);
1617
+ return /* @__PURE__ */ jsx("div", {
1618
+ "aria-keyshortcuts": "Control+V Meta+V",
1619
+ ...rest,
1620
+ ref,
1621
+ id: field.zoneId,
1622
+ role: "region",
1623
+ "aria-label": safeAriaLabel,
1624
+ "data-zone": "",
1625
+ "data-state": field.status,
1626
+ "data-display-state": field.displayStatus,
1627
+ tabIndex: tabIndex ?? (focusable ? 0 : void 0),
1628
+ onPaste: composeEventHandlers(onPaste, targetProps.onPaste),
1629
+ children
1630
+ });
1631
+ });
1632
+ const DEFAULT_TRIGGER_TEXT = {
1633
+ idle: "Paste",
1634
+ reading: "Pasting…",
1635
+ read: "Pasted",
1636
+ error: "Retry"
1637
+ };
1638
+ /**
1639
+ * Headless compound component for a labelled, paste-ready field.
1640
+ *
1641
+ * Styling hooks on Root, Zone and Trigger:
1642
+ * - `data-display-state="idle|reading|read|error"`: flicker-free, style with this
1643
+ * - `data-state`: the real, instantaneous state, for logic and tests
1644
+ * - `data-revealed`: present while the trigger should be visible
1645
+ *
1646
+ * @example
1647
+ * ```tsx
1648
+ * <PasteField.Root label="Notes">
1649
+ * <PasteField.Label />
1650
+ * <PasteField.Zone />
1651
+ * <PasteField.Trigger />
1652
+ * </PasteField.Root>
1653
+ * ```
1654
+ */
1655
+ const PasteField = {
1656
+ Root,
1657
+ Label,
1658
+ Status,
1659
+ Zone,
1660
+ Trigger: /* @__PURE__ */ forwardRef(function PasteFieldTrigger({ children, onClick, "aria-label": ariaLabel, ...rest }, ref) {
1661
+ const field = usePasteField();
1662
+ const renderProps = {
1663
+ status: field.status,
1664
+ displayStatus: field.displayStatus,
1665
+ state: field.state,
1666
+ revealed: field.revealed
1667
+ };
1668
+ const safeAriaLabel = (ariaLabel ?? field.messages.triggerLabel(field.label)) || defaultPasteFieldMessages.triggerLabel(field.label);
1669
+ return /* @__PURE__ */ jsx("button", {
1670
+ ...rest,
1671
+ ref,
1672
+ type: "button",
1673
+ "aria-label": safeAriaLabel,
1674
+ "aria-busy": field.status === "reading" ? true : void 0,
1675
+ "data-state": field.status,
1676
+ "data-display-state": field.displayStatus,
1677
+ "data-revealed": field.revealed ? "" : void 0,
1678
+ onClick: composeEventHandlers(onClick, () => {
1679
+ field.doPaste();
1680
+ }),
1681
+ children: typeof children === "function" ? children(renderProps) : children ?? /* @__PURE__ */ jsx(TriggerLabel, {
1682
+ status: field.displayStatus,
1683
+ labels: DEFAULT_TRIGGER_TEXT
1684
+ })
1685
+ });
1686
+ })
1687
+ };
1688
+ //#endregion
1689
+ export { CopyFailure, CopyField, CopyGroup, DEFAULT_MAX_RETRIES, DEFAULT_MIN_PENDING_MS, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_PASTE_MIN_PENDING_MS, DEFAULT_PASTE_PENDING_DELAY_MS, DEFAULT_PENDING_DELAY_MS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, LiveRegion, PASTE_IDLE_STATE, PasteField, SVG_MIME_TYPE, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, defaultCopyFieldMessages, defaultPasteFieldMessages, describeCopyError, describePasteError, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, useCopy, useCopyField, useCopyGroup, useDisplayStatus, usePaste, usePasteDisplayStatus, usePasteField, useRevealOnInteraction, validatePayload, visuallyHiddenStyle };
1455
1690
 
1456
1691
  //# sourceMappingURL=index.js.map