@enigmax/primitives 0.23.0 → 0.24.0

package/dist/{chunk-DSBYVA7V.js → chunk-DZMHY3SU.js}

@@ -1,4 +1,4 @@
-import { createContextMenu, isAction } from './chunk-3BQVOOAM.js';
+import { createContextMenu, clipboardAction, performClipboardAction, inspectClipboardTarget, CLIPBOARD_PREFIX, clipboardEntries, isAction, clipboardHasText } from './chunk-Z3VDE7OA.js';
 import { shortcutTokens } from './chunk-4VUHQFAT.js';
 import { Slot } from './chunk-HS3X3XCW.js';
 import { shortenQuery } from './chunk-4ZPMP47J.js';
@@ -60,6 +60,14 @@ var CONTEXT_MENU_STYLES = `
     visibility: hidden;
 }
 [data-enigma-menu-panel][data-placed] { visibility: visible; }
+/* No focus ring around the panel. It takes focus so the keyboard has somewhere to be, not
+   because it is a control: what MOVES is the highlighted row, drawn by [data-active] and
+   announced through aria-activedescendant. A ring around the whole menu says the menu is the
+   thing focused, which is not what is happening - and it appears the moment you press an
+   arrow, over a surface that was already showing you where you are. Nothing is lost by
+   removing it, because nothing inside is reachable by Tab: the menu owns that key. */
+[data-enigma-menu-panel]:focus,
+[data-enigma-menu-panel]:focus-visible { outline: none; }
 @keyframes enigma-menu-in {
     from { opacity: 0; transform: scale(0.98); }
     to { opacity: 1; transform: none; }
@@ -184,6 +192,32 @@ function useContextMenuContext(part) {
   if (!value) throw new Error(`<${part}> must be rendered inside <ContextMenu.Root>.`);
   return value;
 }
+var CLIPBOARD_ICON = {
+  viewBox: "0 0 24 24",
+  width: "1em",
+  height: "1em",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 2,
+  strokeLinecap: "round",
+  strokeLinejoin: "round",
+  "aria-hidden": true
+};
+var CLIPBOARD_ICONS = {
+  copy: /* @__PURE__ */ jsxs("svg", { ...CLIPBOARD_ICON, children: [
+    /* @__PURE__ */ jsx("rect", { x: "9", y: "9", width: "12", height: "12", rx: "2" }),
+    /* @__PURE__ */ jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })
+  ] }),
+  cut: /* @__PURE__ */ jsxs("svg", { ...CLIPBOARD_ICON, children: [
+    /* @__PURE__ */ jsx("circle", { cx: "6", cy: "6", r: "3" }),
+    /* @__PURE__ */ jsx("circle", { cx: "6", cy: "18", r: "3" }),
+    /* @__PURE__ */ jsx("path", { d: "M20 4 8.12 15.88M14.47 14.48 20 20M8.12 8.12 12 12" })
+  ] }),
+  paste: /* @__PURE__ */ jsxs("svg", { ...CLIPBOARD_ICON, children: [
+    /* @__PURE__ */ jsx("path", { d: "M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2" }),
+    /* @__PURE__ */ jsx("rect", { x: "8", y: "2", width: "8", height: "4", rx: "1" })
+  ] })
+};
 var injected = false;
 function injectStyles() {
   if (injected || typeof document === "undefined") return;
@@ -223,6 +257,7 @@ function ContextMenuRoot(props) {
     loadingLabel = "Loading...",
     emptyLabel = "Nothing here.",
     styles = true,
+    clipboard = true,
     children
   } = props;
   useLayoutEffect(() => {
@@ -242,7 +277,11 @@ function ContextMenuRoot(props) {
     matcher,
     searchKeys,
     cacheMs,
-    onSelect: (item, path) => latest.current.onSelect?.(item, path),
+    onSelect: (item, path) => {
+      const action = clipboardAction(item.id);
+      if (action) void performClipboardAction(action, clipboardTarget.current);
+      latest.current.onSelect?.(item, path);
+    },
     onOpenChange: (open2) => latest.current.onOpenChange?.(open2)
     // Built once: rebuilding it would drop the open branch and the highlight on every
     // render. Every option below is pushed in through update().
@@ -276,9 +315,21 @@ function ContextMenuRoot(props) {
   }, [items]);
   const currentItems = useRef(items);
   currentItems.current = items;
+  const clipboardTarget = useRef(inspectClipboardTarget(null));
+  const clipboardRows = useRef([]);
+  const clipboardOptions = useMemo(() => {
+    if (clipboard === false) return null;
+    return { icons: CLIPBOARD_ICONS, ...clipboard === true ? {} : clipboard };
+  }, [clipboard]);
+  const withClipboard = useCallback((rows) => {
+    const clip = clipboardRows.current;
+    if (clip.length === 0) return rows;
+    if (rows.length === 0) return clip;
+    return [...clip, { type: "separator", id: `${CLIPBOARD_PREFIX}rule` }, ...rows];
+  }, []);
   useEffect(() => {
-    instance.update({ items: currentItems.current, title });
-  }, [instance, signature, title]);
+    instance.update({ items: withClipboard(currentItems.current), title });
+  }, [instance, signature, title, withClipboard]);
   const cancelClose = useCallback(() => {
     window.clearTimeout(closing.current);
   }, []);
@@ -287,11 +338,23 @@ function ContextMenuRoot(props) {
     closing.current = window.setTimeout(() => instance.closeBelow(level), closeDelay);
   }, [instance, closeDelay]);
   useEffect(() => cancelClose, [cancelClose]);
-  const open = useCallback((point) => {
+  const open = useCallback((point, target) => {
     if (disabled) return false;
     cancelClose();
+    if (clipboardOptions) {
+      clipboardTarget.current = inspectClipboardTarget(target ?? null);
+      clipboardRows.current = clipboardEntries(clipboardTarget.current, clipboardOptions);
+      instance.update({ items: withClipboard(currentItems.current) });
+      if (clipboardRows.current.some((entry) => isAction(entry) && clipboardAction(entry.id) === "paste")) {
+        void clipboardHasText().then((has) => {
+          if (has !== false || !instance.state.open) return;
+          clipboardRows.current = clipboardRows.current.map((entry) => isAction(entry) && clipboardAction(entry.id) === "paste" ? { ...entry, disabled: true } : entry);
+          instance.update({ items: withClipboard(currentItems.current) });
+        });
+      }
+    }
     return instance.open(point);
-  }, [instance, disabled, cancelClose]);
+  }, [instance, disabled, cancelClose, clipboardOptions, withClipboard]);
   const close = useCallback(() => {
     cancelClose();
     instance.close();
@@ -414,16 +477,17 @@ function ContextMenuTrigger({ asChild = false, longPress = true, children, ...pr
       onContextMenu: (event) => {
         props.onContextMenu?.(event);
         if (event.defaultPrevented) return;
-        if (menu.open({ x: event.clientX, y: event.clientY })) event.preventDefault();
+        if (menu.open({ x: event.clientX, y: event.clientY }, event.target)) event.preventDefault();
       },
       onPointerDown: (event) => {
         props.onPointerDown?.(event);
         if (event.defaultPrevented || !longPress || event.pointerType !== "touch") return;
         const { clientX: x, clientY: y } = event;
         cancelPress();
+        const target = event.target;
         press.current = { x, y, timer: window.setTimeout(() => {
           press.current = null;
-          menu.open({ x, y });
+          menu.open({ x, y }, target);
         }, LONG_PRESS_MS) };
       },
       onPointerMove: (event) => {
@@ -445,7 +509,7 @@ function ContextMenuTrigger({ asChild = false, longPress = true, children, ...pr
         const wanted = event.key === "ContextMenu" || event.key === "F10" && event.shiftKey;
         if (!wanted) return;
         const rect = event.currentTarget.getBoundingClientRect();
-        if (menu.open({ x: rect.left + 8, y: rect.top + 8 })) event.preventDefault();
+        if (menu.open({ x: rect.left + 8, y: rect.top + 8 }, document.activeElement)) event.preventDefault();
       },
       children
     }

package/dist/{chunk-KEVZ5XQV.js → chunk-QJJ34E4G.js}

@@ -1,3 +1,4 @@
+import { writeValue } from './chunk-S7EE57YB.js';
 import { INPUT_ICON_PATHS } from './chunk-F25CGNQC.js';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { lazy, forwardRef, useRef, useState, useId, useCallback, useEffect, Suspense } from 'react';
@@ -16,16 +17,15 @@ var ICON_PROPS = {
 function Icon({ paths }) {
   return /* @__PURE__ */ jsx("svg", { ...ICON_PROPS, children: paths.map((path) => /* @__PURE__ */ jsx("path", { d: path }, path)) });
 }
-
-// src/react/input/write-value.ts
-function writeValue(input, next) {
-  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
-  if (setter) setter.call(input, next);
-  else input.value = next;
-  input.dispatchEvent(new Event("input", { bubbles: true }));
-}
+var COLOR_FIELD_PROPS = {
+  autoComplete: "off",
+  autoCorrect: "off",
+  autoCapitalize: "off",
+  spellCheck: false
+};
 var PasswordExtras = lazy(() => import('./password-3DRQYAYQ.js').then((module) => ({ default: module.PasswordExtras })));
 var SearchExtras = lazy(() => import('./search-PBZORZ7P.js').then((module) => ({ default: module.SearchExtras })));
+var ColorExtras = lazy(() => import('./color-OPV3BJV6.js').then((module) => ({ default: module.ColorExtras })));
 var Input = forwardRef(function Input2(props, forwardedRef) {
   const {
     reveal,
@@ -53,6 +53,13 @@ var Input = forwardRef(function Input2(props, forwardedRef) {
     renderResults,
     clearable,
     clearLabel = "Clear",
+    format,
+    alpha,
+    swatches,
+    eyedropper,
+    placement,
+    styles,
+    colorLabels,
     wrapperProps,
     fieldProps,
     classNames,
@@ -67,6 +74,7 @@ var Input = forwardRef(function Input2(props, forwardedRef) {
   const describedBy = useId();
   const isPassword = type === "password";
   const isSearch = type === "search";
+  const isColor = type === "color";
   const showReveal = reveal ?? isPassword;
   const showGenerate = generate !== false && isPassword;
   const showClear = (clearable ?? isSearch) && isSearch;
@@ -192,10 +200,26 @@ var Input = forwardRef(function Input2(props, forwardedRef) {
       "data-score": score ?? void 0,
       children: [
         /* @__PURE__ */ jsxs("div", { ...fieldProps, "data-enigma-input-field": "", children: [
+          isColor && /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(
+            ColorExtras,
+            {
+              input: element,
+              value,
+              format,
+              alpha,
+              swatches,
+              eyedropper,
+              placement,
+              styles,
+              locked,
+              labels: colorLabels
+            }
+          ) }),
           position === "start" && buttons,
           /* @__PURE__ */ jsx(
             "input",
             {
+              ...isColor ? COLOR_FIELD_PROPS : null,
               ...rest,
               ref: (node) => {
                 innerRef.current = node;
@@ -203,7 +227,7 @@ var Input = forwardRef(function Input2(props, forwardedRef) {
                 if (typeof forwardedRef === "function") forwardedRef(node);
                 else if (forwardedRef) forwardedRef.current = node;
               },
-              type: revealed && isPassword ? "text" : type,
+              type: isColor ? "text" : revealed && isPassword ? "text" : type,
               onChange: handleChange,
               "data-enigma-input": "",
               "aria-describedby": score !== null ? describedBy : rest["aria-describedby"]

package/dist/chunk-S2FPN5ID.js

@@ -0,0 +1,115 @@
+// src/core/color.ts
+function clamp(value, min, max) {
+  return value < min ? min : value > max ? max : value;
+}
+function clampAlpha(value) {
+  return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
+}
+function channel(value) {
+  return Math.round(clamp(value, 0, 255));
+}
+function ratio(token, scale) {
+  const text = token.trim();
+  const value = Number.parseFloat(text);
+  if (!Number.isFinite(value)) return Number.NaN;
+  return text.endsWith("%") ? value / 100 * scale : value;
+}
+function components(body) {
+  return body.split(/[\s,/]+/).map((part) => part.trim()).filter(Boolean);
+}
+function parseColor(input) {
+  const text = input.trim().toLowerCase();
+  if (!text) return null;
+  if (text === "transparent") return { r: 0, g: 0, b: 0, a: 0 };
+  const hex = /^#?([0-9a-f]+)$/.exec(text);
+  if (hex) return fromHex(hex[1]);
+  const functional = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);
+  if (!functional) return null;
+  const parts = components(functional[2]);
+  if (parts.length < 3 || parts.length > 4) return null;
+  const alpha = parts.length === 4 ? clampAlpha(ratio(parts[3], 1)) : 1;
+  if (functional[1].startsWith("rgb")) {
+    const values = parts.slice(0, 3).map((part) => ratio(part, 255));
+    if (values.some((value) => !Number.isFinite(value))) return null;
+    return { r: channel(values[0]), g: channel(values[1]), b: channel(values[2]), a: alpha };
+  }
+  const hue = Number.parseFloat(parts[0]);
+  const saturation = ratio(parts[1], 1);
+  const lightness = ratio(parts[2], 1);
+  if (!Number.isFinite(hue) || !Number.isFinite(saturation) || !Number.isFinite(lightness)) return null;
+  return hslToRgb({ h: hue, s: clamp(saturation, 0, 1), l: clamp(lightness, 0, 1), a: alpha });
+}
+function fromHex(digits) {
+  const size = digits.length;
+  if (size !== 3 && size !== 4 && size !== 6 && size !== 8) return null;
+  const short = size <= 4;
+  const at = (index) => {
+    const slice = short ? digits[index].repeat(2) : digits.slice(index * 2, index * 2 + 2);
+    return Number.parseInt(slice, 16);
+  };
+  const alpha = size === 4 || size === 8 ? at(3) / 255 : 1;
+  return { r: at(0), g: at(1), b: at(2), a: clampAlpha(alpha) };
+}
+function toHex(color, options = {}) {
+  const pair = (value) => channel(value).toString(16).padStart(2, "0");
+  const alpha = clampAlpha(color.a);
+  const suffix = options.alpha && alpha < 1 ? pair(Math.round(alpha * 255)) : "";
+  return `#${pair(color.r)}${pair(color.g)}${pair(color.b)}${suffix}`;
+}
+function formatColor(color, format = "hex", options = {}) {
+  const alpha = clampAlpha(color.a);
+  const opaque = !options.alpha || alpha >= 1;
+  const printed = Number.parseFloat(alpha.toFixed(3));
+  if (format === "hex") return toHex(color, options);
+  if (format === "rgb") {
+    const body2 = `${channel(color.r)}, ${channel(color.g)}, ${channel(color.b)}`;
+    return opaque ? `rgb(${body2})` : `rgba(${body2}, ${printed})`;
+  }
+  const hsl = rgbToHsl(color);
+  const body = `${Math.round(hsl.h)}, ${Math.round(hsl.s * 100)}%, ${Math.round(hsl.l * 100)}%`;
+  return opaque ? `hsl(${body})` : `hsla(${body}, ${printed})`;
+}
+function rgbToHsv(color, fallbackHue = 0) {
+  const r = clamp(color.r, 0, 255) / 255;
+  const g = clamp(color.g, 0, 255) / 255;
+  const b = clamp(color.b, 0, 255) / 255;
+  const max = Math.max(r, g, b);
+  const span = max - Math.min(r, g, b);
+  let h = fallbackHue;
+  if (span > 0) {
+    if (max === r) h = (g - b) / span % 6;
+    else if (max === g) h = (b - r) / span + 2;
+    else h = (r - g) / span + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h, s: max === 0 ? 0 : span / max, v: max, a: clampAlpha(color.a) };
+}
+function hsvToRgb(color) {
+  const h = (color.h % 360 + 360) % 360;
+  const s = clamp(color.s, 0, 1);
+  const v = clamp(color.v, 0, 1);
+  const c = v * s;
+  const x = c * (1 - Math.abs(h / 60 % 2 - 1));
+  const m = v - c;
+  const [r, g, b] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  return { r: channel((r + m) * 255), g: channel((g + m) * 255), b: channel((b + m) * 255), a: clampAlpha(color.a) };
+}
+function rgbToHsl(color, fallbackHue = 0) {
+  const hsv = rgbToHsv(color, fallbackHue);
+  const l = hsv.v * (1 - hsv.s / 2);
+  const s = l === 0 || l === 1 ? 0 : (hsv.v - l) / Math.min(l, 1 - l);
+  return { h: hsv.h, s: clamp(s, 0, 1), l, a: hsv.a };
+}
+function hslToRgb(color) {
+  const s = clamp(color.s, 0, 1);
+  const l = clamp(color.l, 0, 1);
+  const v = l + s * Math.min(l, 1 - l);
+  return hsvToRgb({ h: color.h, s: v === 0 ? 0 : 2 * (1 - l / v), v, a: color.a });
+}
+function colorEquals(a, b) {
+  if (!a || !b) return a === b;
+  return channel(a.r) === channel(b.r) && channel(a.g) === channel(b.g) && channel(a.b) === channel(b.b) && Math.round(clampAlpha(a.a) * 255) === Math.round(clampAlpha(b.a) * 255);
+}
+
+export { colorEquals, formatColor, hslToRgb, hsvToRgb, parseColor, rgbToHsl, rgbToHsv, toHex };

package/dist/chunk-S7EE57YB.js

@@ -0,0 +1,9 @@
+// src/react/input/write-value.ts
+function writeValue(input, next) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  if (setter) setter.call(input, next);
+  else input.value = next;
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+export { writeValue };

package/dist/{chunk-3BQVOOAM.js → chunk-Z3VDE7OA.js}

@@ -385,4 +385,148 @@ function createContextMenu(options = {}) {
   };
 }
 
-export { CONTEXT_MENU_SEARCH_KEYS, createContextMenu, isAction };
+// src/core/clipboard-menu.ts
+var CLIPBOARD_PREFIX = "enigma:clipboard:";
+var SELECTABLE_TYPES = /* @__PURE__ */ new Set(["text", "search", "url", "tel", "password"]);
+var EMPTY = { editable: null, writable: false, selection: "", copyable: true, range: null };
+function isEditableElement(node) {
+  return Boolean(node && node.isContentEditable);
+}
+function documentSelection(element) {
+  const selection = typeof window === "undefined" ? null : window.getSelection();
+  if (!selection || selection.isCollapsed || selection.rangeCount === 0) return "";
+  const range = selection.getRangeAt(0);
+  if (element && !range.intersectsNode(element)) return "";
+  return selection.toString();
+}
+function inspectClipboardTarget(node) {
+  if (typeof document === "undefined") return EMPTY;
+  const element = node instanceof Element ? node : null;
+  const field = element?.closest?.("input, textarea");
+  if (field) {
+    const password = field instanceof HTMLInputElement && field.type === "password";
+    const selectable = field instanceof HTMLTextAreaElement || SELECTABLE_TYPES.has(field.type);
+    const start = selectable ? field.selectionStart ?? 0 : 0;
+    const end = selectable ? field.selectionEnd ?? 0 : 0;
+    return {
+      editable: field,
+      writable: !field.disabled && !field.readOnly,
+      selection: selectable ? field.value.slice(start, end) : "",
+      copyable: !password,
+      range: selectable ? { start, end } : null
+    };
+  }
+  const editable = isEditableElement(element) ? element.closest("[contenteditable]") ?? element : null;
+  return {
+    editable,
+    writable: Boolean(editable),
+    selection: documentSelection(element),
+    copyable: true,
+    // A contenteditable's selection is a live DOM Range the browser keeps for us; there is
+    // no pair of offsets to restore, and re-focusing the element puts the caret back.
+    range: null
+  };
+}
+async function clipboardHasText() {
+  if (typeof navigator === "undefined" || !navigator.clipboard?.readText) return null;
+  try {
+    const status = await navigator.permissions?.query({ name: "clipboard-read" });
+    if (status?.state !== "granted") return null;
+    return (await navigator.clipboard.readText()).length > 0;
+  } catch {
+    return null;
+  }
+}
+function clipboardEntries(target, options = {}) {
+  const { copy = true, cut = true, paste = true, labels = {}, icons = {}, clipboardEmpty = false } = options;
+  const entries = [];
+  const selected = target.selection.length > 0 && target.copyable;
+  const canPaste = typeof navigator !== "undefined" && Boolean(navigator.clipboard?.readText);
+  if (copy && selected) {
+    entries.push({ id: `${CLIPBOARD_PREFIX}copy`, label: labels.copy ?? "Copy", shortcut: "Mod+C", icon: icons.copy });
+  }
+  if (cut && selected && target.writable) {
+    entries.push({ id: `${CLIPBOARD_PREFIX}cut`, label: labels.cut ?? "Cut", shortcut: "Mod+X", icon: icons.cut });
+  }
+  if (paste && target.writable && canPaste) {
+    entries.push({
+      id: `${CLIPBOARD_PREFIX}paste`,
+      label: labels.paste ?? "Paste",
+      shortcut: "Mod+V",
+      icon: icons.paste,
+      // Listed and greyed rather than dropped: a row that disappears between two opens
+      // is read as the menu being unreliable, and every desktop menu greys this one.
+      disabled: clipboardEmpty
+    });
+  }
+  return entries;
+}
+function clipboardAction(id) {
+  if (!id.startsWith(CLIPBOARD_PREFIX)) return null;
+  const action = id.slice(CLIPBOARD_PREFIX.length);
+  return action === "copy" || action === "cut" || action === "paste" ? action : null;
+}
+function restore(target) {
+  const element = target.editable;
+  if (!element) return;
+  element.focus({ preventScroll: true });
+  if (!target.range) return;
+  const field = element;
+  try {
+    field.setSelectionRange(target.range.start, target.range.end);
+  } catch {
+  }
+}
+function writeFieldValue(field, next) {
+  const prototype = field instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+  if (setter) setter.call(field, next);
+  else field.value = next;
+  field.dispatchEvent(new Event("input", { bubbles: true }));
+}
+function replaceSelection(target, text) {
+  const element = target.editable;
+  if (!element) return;
+  try {
+    if (document.execCommand("insertText", false, text)) return;
+  } catch {
+  }
+  const field = element;
+  if (typeof field.setSelectionRange !== "function" || target.range === null) return;
+  const start = field.selectionStart ?? target.range.start;
+  const end = field.selectionEnd ?? target.range.end;
+  writeFieldValue(field, field.value.slice(0, start) + text + field.value.slice(end));
+  const caret = start + text.length;
+  try {
+    field.setSelectionRange(caret, caret);
+  } catch {
+  }
+}
+async function performClipboardAction(action, target) {
+  restore(target);
+  if (action === "copy" || action === "cut") {
+    if (!target.selection || !target.copyable) return false;
+    try {
+      await navigator.clipboard.writeText(target.selection);
+    } catch {
+      try {
+        if (!document.execCommand("copy")) return false;
+      } catch {
+        return false;
+      }
+    }
+    if (action === "cut" && target.writable) replaceSelection(target, "");
+    return true;
+  }
+  if (!target.writable) return false;
+  try {
+    const text = await navigator.clipboard.readText();
+    if (!text) return false;
+    replaceSelection(target, text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { CLIPBOARD_PREFIX, CONTEXT_MENU_SEARCH_KEYS, clipboardAction, clipboardEntries, clipboardHasText, createContextMenu, inspectClipboardTarget, isAction, performClipboardAction };

package/dist/{context-menu-D3FtTn7v.d.ts → clipboard-menu-B_ouitfS.d.ts}

@@ -171,4 +171,94 @@ interface ContextMenuInstance {
 type ContextMenuMoveKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
 declare function createContextMenu(options?: ContextMenuOptions): ContextMenuInstance;
 
-export { CONTEXT_MENU_SEARCH_KEYS as C, type ContextMenuAction as a, type ContextMenuEntry as b, type ContextMenuInstance as c, type ContextMenuLabel as d, type ContextMenuLevel as e, type ContextMenuMoveKey as f, type ContextMenuOptions as g, type ContextMenuPoint as h, type ContextMenuSeparator as i, type ContextMenuState as j, createContextMenu as k, isAction as l };
+/**
+ * The rows every context menu on a desktop already has: Copy, Cut and Paste.
+ *
+ * A menu opened over a selection or over a field is expected to offer them - the browser's own
+ * does, and replacing that menu with a custom one takes them away without saying so. Which is
+ * why they are ON by default here and turned off with a prop, rather than the other way round:
+ * the defect is silent, so the default has to be the safe one.
+ *
+ * WHAT DECIDES THEY APPEAR is what was right-clicked, and it is read at the moment the menu
+ * opens, not from React state - by then the selection is settled (a `contextmenu` event fires
+ * after the press has adjusted it) and the caret is still where the visitor left it.
+ *
+ * - **Copy**, when there is selected text under the pointer.
+ * - **Cut**, when that selection is also in something writable.
+ * - **Paste**, in anything writable - and disabled when the clipboard is known to be empty.
+ *
+ * Not a React module: what a selection is, whether a field takes writes, and how text is put
+ * back into one are DOM questions, so a menu drawn by anything else gets the same rows.
+ */
+
+/** The ids these rows carry. Namespaced, so they can never collide with a caller's own. */
+declare const CLIPBOARD_PREFIX = "enigma:clipboard:";
+type ClipboardAction = "copy" | "cut" | "paste";
+/** What the menu was opened over, as far as the clipboard is concerned. */
+interface ClipboardTarget {
+    /** The field or contenteditable under the pointer, or null when it is neither. */
+    editable: HTMLElement | null;
+    /** Whether that element takes writes: not disabled, not read-only. */
+    writable: boolean;
+    /** The selected text, from the field's own selection or the document's. */
+    selection: string;
+    /**
+     * Whether that text may be put on the clipboard.
+     *
+     * False for a password field. The clipboard is shared with every other application on the
+     * machine and is not cleared, so a menu that copies a password out of a masked field
+     * leaks it somewhere the visitor cannot see - and the browser's own menu refuses too.
+     */
+    copyable: boolean;
+    /** Where the selection was, so it can be put back after the menu has taken focus. */
+    range: {
+        start: number;
+        end: number;
+    } | null;
+}
+interface ClipboardMenuLabels {
+    copy?: string;
+    cut?: string;
+    paste?: string;
+}
+interface ClipboardMenuOptions {
+    copy?: boolean;
+    cut?: boolean;
+    paste?: boolean;
+    labels?: ClipboardMenuLabels;
+    /** Whatever the renderer draws icons with. `unknown`, because a core cannot know. */
+    icons?: {
+        copy?: unknown;
+        cut?: unknown;
+        paste?: unknown;
+    };
+    /** The clipboard is known to be empty, so Paste is listed and greyed rather than missing. */
+    clipboardEmpty?: boolean;
+}
+/** What was right-clicked, read the moment the menu opens. */
+declare function inspectClipboardTarget(node: EventTarget | null): ClipboardTarget;
+/**
+ * Whether the clipboard has text in it, or null when that cannot be known.
+ *
+ * Null is the common answer and not a failure: reading the clipboard needs permission, and
+ * asking for it puts a browser prompt on screen just to decide whether to grey out a row -
+ * which is a worse trade than showing an enabled Paste that turns out to do nothing. So the
+ * permission is only READ, never requested, and the clipboard is only opened where it has
+ * already been granted.
+ */
+declare function clipboardHasText(): Promise<boolean | null>;
+/** The rows for this target, in the order every desktop menu puts them. */
+declare function clipboardEntries(target: ClipboardTarget, options?: ClipboardMenuOptions): ContextMenuEntry[];
+/** Which clipboard row an id belongs to, or null for anything that is not one of ours. */
+declare function clipboardAction(id: string): ClipboardAction | null;
+/**
+ * Do what the row says.
+ *
+ * Called straight from the press that chose it, so the browser still counts it as a user
+ * gesture - which is what the clipboard API requires and what makes a paste possible at all.
+ * Returns whether the action happened: a refused permission and an empty clipboard are both
+ * "no", and neither is worth an exception the caller has to catch.
+ */
+declare function performClipboardAction(action: ClipboardAction, target: ClipboardTarget): Promise<boolean>;
+
+export { CLIPBOARD_PREFIX as C, CONTEXT_MENU_SEARCH_KEYS as a, type ClipboardAction as b, type ClipboardMenuLabels as c, type ClipboardMenuOptions as d, type ClipboardTarget as e, type ContextMenuAction as f, type ContextMenuEntry as g, type ContextMenuInstance as h, type ContextMenuLabel as i, type ContextMenuLevel as j, type ContextMenuMoveKey as k, type ContextMenuOptions as l, type ContextMenuPoint as m, type ContextMenuSeparator as n, type ContextMenuState as o, clipboardAction as p, clipboardEntries as q, clipboardHasText as r, createContextMenu as s, inspectClipboardTarget as t, isAction as u, performClipboardAction as v };