@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/clipboard/LegacyCopy.d.ts

@@ -0,0 +1,38 @@
+import { ClipboardCopyOptions, ClipboardWriteResult } from './ClipboardResult';
+/**
+ * Copies `text` through the deprecated `document.execCommand('copy')` path.
+ *
+ * Synchronous, unlike every other write in this slice — `execCommand` is. Requires a user gesture: outside one
+ * the command reports its own refusal by returning `false`, which surfaces here as `failed` (the legacy API has
+ * no way to say "denied" specifically). Returns `unsupported` under SSR or where `execCommand` is gone.
+ *
+ * Exported for the sibling modules and for a consumer that wants the legacy path explicitly; the temporary
+ * element is removed on every path, including a throw from `execCommand` itself.
+ *
+ * Never throws.
+ *
+ * @param text The text to place on the clipboard.
+ * @deprecated Prefer `copyText`, which uses the Clipboard API and falls back here only on `legacyFallback: true`.
+ */
+export declare function legacyCopyText(text: string): ClipboardWriteResult;
+/**
+ * Retries a write that the Clipboard API could not complete through the legacy path, when the caller opted in.
+ *
+ * The retry runs whenever `modern` is not `copied` — not only on `unsupported`. A `denied` from
+ * `navigator.clipboard` is exactly the case `execCommand` can still serve: the legacy command is gated on the
+ * user gesture the call already sits in, not on the Clipboard API's permission.
+ *
+ * Which result wins:
+ *  - the legacy attempt, when it copied — a success outranks any diagnosis;
+ *  - otherwise `modern`, when the Clipboard API was actually present (its `denied` / `failed` is the more
+ *    specific account of what went wrong);
+ *  - otherwise the legacy attempt's own result — with no Clipboard API at all, `modern` is a bare `unsupported`
+ *    and the legacy failure says more.
+ *
+ * Exported for the sibling write modules; absent from the barrel. Never throws.
+ *
+ * @param modern The result the Clipboard API path produced.
+ * @param text The plain-text payload, or `undefined` when the write has no text arm to degrade to.
+ * @param options The caller's options — the retry runs only on `legacyFallback: true`.
+ */
+export declare function withLegacyFallback(modern: ClipboardWriteResult, text: string | undefined, options: ClipboardCopyOptions | undefined): ClipboardWriteResult;

package/dist/foundation/clipboard/PasteItems.d.ts

@@ -0,0 +1,25 @@
+/** What a paste carried, normalized to the three representations a consumer acts on. */
+export interface PasteItems {
+    /** The `text/plain` representation, or `undefined` when the paste carried none (a bare image paste). */
+    readonly text: string | undefined;
+    /** The `text/html` representation, or `undefined`. Present when copying from a rich source — sanitize before rendering. */
+    readonly html: string | undefined;
+    /** Files on the paste — a screenshot, an image, a document. Empty when the paste was text only. */
+    readonly files: readonly File[];
+}
+/**
+ * Extracts the text, HTML, and files a `paste` event carried.
+ *
+ * Needs no permission and no user gesture — the event IS the user's authorization — and works in every engine,
+ * including the ones that withhold `navigator.clipboard.read`. This is the path to build "paste an image"
+ * features on.
+ *
+ * Does not call `preventDefault`: suppressing the browser's own paste is the consumer's decision, and a handler
+ * that reads the payload for a side effect usually wants the default insert to happen too. `usePasteHandler`
+ * exposes it as an option.
+ *
+ * Never throws — a malformed or partial event yields `{ text: undefined, html: undefined, files: [] }`.
+ *
+ * @param event The `paste` event, from a `@paste` binding or a native listener.
+ */
+export declare function getPasteItems(event: ClipboardEvent): PasteItems;

package/dist/foundation/clipboard/ReadClipboard.d.ts

@@ -0,0 +1,29 @@
+import { ClipboardReadItemsResult, ClipboardReadOptions, ClipboardReadTextResult } from './ClipboardResult';
+/**
+ * Reads the clipboard's plain text.
+ *
+ * Requires a user gesture and, in Chromium, an explicit permission prompt the user can dismiss — a dismissal is
+ * `denied`. Resolves to `unsupported` under SSR and in Firefox, which withholds clipboard reading from page
+ * script entirely.
+ *
+ * Prefer `getPasteItems` on a `paste` event wherever the flow is "the user pastes something": that path needs no
+ * permission and works everywhere.
+ *
+ * Never throws, never rejects.
+ *
+ * @param options Error reporting.
+ */
+export declare function readText(options?: ClipboardReadOptions): Promise<ClipboardReadTextResult>;
+/**
+ * Reads every representation currently on the clipboard — the multi-format counterpart of {@link readText}, and
+ * the only way to pull a copied image.
+ *
+ * Same gating as {@link readText}, and narrower support still: `navigator.clipboard.read` postdates `readText`
+ * in every engine that has it. Representations the platform cannot materialize are dropped from the result
+ * rather than failing the whole read.
+ *
+ * Never throws, never rejects.
+ *
+ * @param options Error reporting.
+ */
+export declare function readItems(options?: ClipboardReadOptions): Promise<ClipboardReadItemsResult>;

package/dist/foundation/clipboard/UseClipboardCopy.d.ts

@@ -0,0 +1,40 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { ClipboardCopyOptions, ClipboardWriteResult, ClipboardWriteStatus } from './ClipboardResult';
+/** Where a {@link useClipboardCopy} instance sits: `idle` before the first attempt, otherwise the last outcome. */
+export type ClipboardCopyState = 'idle' | ClipboardWriteStatus;
+/** Tunes a {@link useClipboardCopy} instance. */
+export interface UseClipboardCopyOptions extends ClipboardCopyOptions {
+    /**
+     * How long `status` holds the last outcome before returning to `idle`, in milliseconds. Defaults to 2000 —
+     * long enough to read "Copied!", short enough not to linger.
+     *
+     * Pass `0` to hold the status until {@link ClipboardCopyControls.reset} is called, which is what a failure
+     * message the user must acknowledge wants.
+     */
+    readonly resetAfterMs?: number;
+}
+/** What {@link useClipboardCopy} returns. */
+export interface ClipboardCopyControls {
+    /**
+     * The last outcome, or `idle` before the first attempt and after the reset window. Drives the icon swap, the
+     * "Copied!" label, and the `denied` / `unsupported` fallback copy.
+     */
+    readonly status: Readonly<ShallowRef<ClipboardCopyState>>;
+    /**
+     * Writes `text` to the clipboard and resolves to the full result — the awaiting caller branches on the
+     * outcome, while `status` drives the render. Never throws, never rejects.
+     */
+    readonly copy: (text: string) => Promise<ClipboardWriteResult>;
+    /** Returns `status` to `idle` immediately and cancels the pending auto-reset. */
+    readonly reset: () => void;
+}
+/**
+ * Wraps `copyText` in a transient status for post-action UI, without swallowing the outcome.
+ *
+ * Call `copy` from a user gesture — the platform requires transient activation, and a copy fired from a watcher
+ * or a timeout comes back `denied`.
+ *
+ * @param options Error reporting, the legacy-fallback opt-in, and the auto-reset window. Read fresh on every
+ *   call, so a ref or getter keeps them live.
+ */
+export declare function useClipboardCopy(options?: MaybeRefOrGetter<UseClipboardCopyOptions | undefined>): ClipboardCopyControls;

package/dist/foundation/clipboard/UsePasteHandler.d.ts

@@ -0,0 +1,35 @@
+import { MaybeRefOrGetter } from 'vue';
+import { PasteItems } from './PasteItems';
+/** Tunes a {@link usePasteHandler} binding. */
+export interface UsePasteHandlerOptions {
+    /**
+     * The element to listen on. Defaults to `window`, which catches a paste anywhere on the page — the right
+     * default for a drop-zone or an editor surface that is not itself focused. Pass a ref or getter to scope the
+     * listener to one element.
+     */
+    readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /**
+     * Whether the listener is attached. Defaults to `true`; pass `false` to suspend it without tearing down — a
+     * modal that should own pastes only while open.
+     */
+    readonly enabled?: MaybeRefOrGetter<boolean | undefined>;
+    /**
+     * Whether to call `preventDefault()` on the event, suppressing the browser's own paste. Defaults to `false`.
+     *
+     * Turn it on when the handler fully owns the paste (inserting the image itself); leave it off when the handler
+     * is a side effect and the default insert should still happen. Applied BEFORE the handler runs, so a throw
+     * from the handler cannot skip it.
+     */
+    readonly preventDefault?: MaybeRefOrGetter<boolean | undefined>;
+}
+/**
+ * Binds a `paste` listener that hands the handler the event's already-extracted text, HTML, and files.
+ *
+ * Needs no clipboard permission — see `PasteItems.ts` for why this is the path to prefer over `readText`.
+ * Detaches on scope disposal, and on any change to `enabled` / `target` / `preventDefault`.
+ *
+ * @param handler Called on every paste with the extracted payload and the original event. A throw from it is
+ *   swallowed.
+ * @param options Where to listen, whether to listen, and whether to suppress the default paste.
+ */
+export declare function usePasteHandler(handler: (items: PasteItems, event: ClipboardEvent) => void, options?: UsePasteHandlerOptions): void;

package/dist/foundation/clipboard/index.d.ts

@@ -0,0 +1,10 @@
+export { type ClipboardFailure, type ClipboardWriteResult, type ClipboardWriteStatus, type ClipboardReadItem, type ClipboardReadTextResult, type ClipboardReadItemsResult, type ClipboardReadStatus, type ClipboardReadOptions, type ClipboardCopyOptions, } from './ClipboardResult';
+export { canCopy, canCopyItems, canReadClipboard, canLegacyCopy, } from './ClipboardSupport';
+export { copyText } from './CopyText';
+export { copyItems, copyBlob, type ClipboardWriteItems } from './CopyItems';
+export { legacyCopyText } from './LegacyCopy';
+export { readText, readItems } from './ReadClipboard';
+export { getPasteItems, type PasteItems } from './PasteItems';
+export { usePasteHandler, type UsePasteHandlerOptions } from './UsePasteHandler';
+export { useClipboardCopy, type ClipboardCopyControls, type ClipboardCopyState, type UseClipboardCopyOptions, } from './UseClipboardCopy';
+export { getClipboardPermission, type ClipboardPermissionMode } from './ClipboardPermission';

package/dist/foundation/clipboard/index.js

@@ -0,0 +1,437 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { watchPostEffect, toValue, shallowRef, onScopeDispose } from "vue";
+import { q as queryPermission } from "../../chunks/QueryPermission--OKfvS9c.js";
+function nameOf(value) {
+  try {
+    if (typeof value !== "object" || value === null) return void 0;
+    const name = value.name;
+    return typeof name === "string" ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isPermissionRefusal(value) {
+  const name = nameOf(value);
+  return name === "NotAllowedError" || name === "SecurityError";
+}
+function toClipboardFailure(error) {
+  const failure = toError(error);
+  return isPermissionRefusal(error) ? { status: "denied", error: failure } : { status: "failed", error: failure };
+}
+function reportClipboardOutcome(result, onError) {
+  if (onError === void 0) return result;
+  if (result.error === void 0) return result;
+  try {
+    onError(result.error);
+  } catch {
+  }
+  return result;
+}
+function member$1(source, key) {
+  try {
+    return source[key];
+  } catch {
+    return void 0;
+  }
+}
+function clipboardApi() {
+  try {
+    if (typeof navigator === "undefined") return void 0;
+    const clipboard = member$1(navigator, "clipboard");
+    if (typeof clipboard !== "object" || clipboard === null) return void 0;
+    return clipboard;
+  } catch {
+    return void 0;
+  }
+}
+function clipboardMethod(name) {
+  const clipboard = clipboardApi();
+  if (clipboard === void 0) return void 0;
+  const method = member$1(clipboard, name);
+  if (typeof method !== "function") return void 0;
+  try {
+    return method.bind(clipboard);
+  } catch {
+    return void 0;
+  }
+}
+function clipboardItemConstructor() {
+  try {
+    const constructor = member$1(globalThis, "ClipboardItem");
+    if (typeof constructor !== "function") return void 0;
+    return constructor;
+  } catch {
+    return void 0;
+  }
+}
+function canCopy() {
+  return clipboardMethod("writeText") !== void 0;
+}
+function canCopyItems() {
+  return clipboardMethod("write") !== void 0 && clipboardItemConstructor() !== void 0;
+}
+function canReadClipboard() {
+  return clipboardMethod("readText") !== void 0;
+}
+function canLegacyCopy() {
+  try {
+    if (typeof document === "undefined") return false;
+    return typeof member$1(document, "execCommand") === "function";
+  } catch {
+    return false;
+  }
+}
+const HiddenTextareaCss = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;margin:0;border:none;outline:none;box-shadow:none;background:transparent;opacity:0;pointer-events:none;";
+function restoreFocus(previous) {
+  try {
+    if (previous === null) return;
+    const focus = previous.focus;
+    if (typeof focus !== "function") return;
+    previous.focus({ preventScroll: true });
+  } catch {
+  }
+}
+function detach(element) {
+  try {
+    if (typeof element.remove === "function") {
+      element.remove();
+      return;
+    }
+    element.parentNode?.removeChild(element);
+  } catch {
+  }
+}
+function legacyCopyText(text) {
+  if (!canLegacyCopy()) return { status: "unsupported" };
+  let element;
+  let previouslyFocused = null;
+  try {
+    const body = document.body;
+    if (typeof body !== "object" || body === null) return { status: "unsupported" };
+    previouslyFocused = document.activeElement;
+    element = document.createElement("textarea");
+    element.value = text;
+    element.setAttribute("aria-hidden", "true");
+    element.setAttribute("tabindex", "-1");
+    element.setAttribute("readonly", "readonly");
+    element.style.cssText = HiddenTextareaCss;
+    body.appendChild(element);
+    element.focus({ preventScroll: true });
+    element.select();
+    element.setSelectionRange(0, text.length);
+    const copied = document.execCommand("copy");
+    return copied ? { status: "copied" } : { status: "failed", error: new Error('document.execCommand("copy") reported failure.') };
+  } catch (error) {
+    return toClipboardFailure(error);
+  } finally {
+    if (element !== void 0) detach(element);
+    restoreFocus(previouslyFocused);
+  }
+}
+function withLegacyFallback(modern, text, options) {
+  if (modern.status === "copied") return modern;
+  if (options?.legacyFallback !== true) return modern;
+  if (text === void 0) return modern;
+  const legacy = legacyCopyText(text);
+  if (legacy.status === "copied") return legacy;
+  return modern.status === "unsupported" ? legacy : modern;
+}
+async function writeTextThroughApi(text) {
+  const writeText = clipboardMethod("writeText");
+  if (writeText === void 0) return { status: "unsupported" };
+  try {
+    await writeText(text);
+    return { status: "copied" };
+  } catch (error) {
+    return toClipboardFailure(error);
+  }
+}
+async function copyText(text, options) {
+  try {
+    if (typeof text !== "string") {
+      return reportClipboardOutcome(
+        { status: "failed", error: new TypeError("copyText expects a string.") },
+        options?.onError
+      );
+    }
+    const result = withLegacyFallback(await writeTextThroughApi(text), text, options);
+    return reportClipboardOutcome(result, options?.onError);
+  } catch (error) {
+    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);
+  }
+}
+const FallbackMimeType = "application/octet-stream";
+const PlainTextMimeType = "text/plain";
+function plainTextArm(items) {
+  try {
+    const value = items[PlainTextMimeType];
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toBlobRecord(items) {
+  const record = {};
+  for (const [type, value] of Object.entries(items)) {
+    record[type] = typeof value === "string" ? new Blob([value], { type }) : value;
+  }
+  return record;
+}
+async function writeItemsThroughApi(items) {
+  const write = clipboardMethod("write");
+  const ClipboardItemConstructor = clipboardItemConstructor();
+  if (write === void 0 || ClipboardItemConstructor === void 0) return { status: "unsupported" };
+  try {
+    await write([new ClipboardItemConstructor(toBlobRecord(items))]);
+    return { status: "copied" };
+  } catch (error) {
+    return toClipboardFailure(error);
+  }
+}
+async function copyItems(items, options) {
+  try {
+    if (typeof items !== "object" || items === null) {
+      return reportClipboardOutcome(
+        { status: "failed", error: new TypeError("copyItems expects an object keyed by MIME type.") },
+        options?.onError
+      );
+    }
+    if (Object.keys(items).length === 0) {
+      return reportClipboardOutcome(
+        { status: "failed", error: new Error("copyItems was given no representations to write.") },
+        options?.onError
+      );
+    }
+    const result = withLegacyFallback(await writeItemsThroughApi(items), plainTextArm(items), options);
+    return reportClipboardOutcome(result, options?.onError);
+  } catch (error) {
+    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);
+  }
+}
+async function copyBlob(blob, mimeType, options) {
+  try {
+    if (typeof blob !== "object" || blob === null) {
+      return reportClipboardOutcome(
+        { status: "failed", error: new TypeError("copyBlob expects a Blob.") },
+        options?.onError
+      );
+    }
+    const ownType = blob.type;
+    const type = mimeType ?? (typeof ownType === "string" && ownType.length > 0 ? ownType : FallbackMimeType);
+    return await copyItems({ [type]: blob }, options);
+  } catch (error) {
+    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);
+  }
+}
+async function flattenItem(item) {
+  const flattened = [];
+  let types;
+  try {
+    const declared = item.types;
+    if (!Array.isArray(declared)) return flattened;
+    types = declared;
+  } catch {
+    return flattened;
+  }
+  for (const type of types) {
+    if (typeof type !== "string") continue;
+    try {
+      const blob = await item.getType(type);
+      if (typeof blob === "object" && blob !== null) flattened.push({ type, blob });
+    } catch {
+    }
+  }
+  return flattened;
+}
+async function readText(options) {
+  try {
+    const read = clipboardMethod("readText");
+    if (read === void 0) return { status: "unsupported" };
+    const text = await read();
+    return typeof text === "string" ? { status: "read", text } : reportClipboardOutcome(
+      {
+        status: "failed",
+        error: new TypeError("navigator.clipboard.readText resolved with a non-string.")
+      },
+      options?.onError
+    );
+  } catch (error) {
+    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);
+  }
+}
+async function readItems(options) {
+  try {
+    const read = clipboardMethod("read");
+    if (read === void 0) return { status: "unsupported" };
+    const raw = await read();
+    if (!Array.isArray(raw)) {
+      return reportClipboardOutcome(
+        { status: "failed", error: new TypeError("navigator.clipboard.read resolved with a non-array.") },
+        options?.onError
+      );
+    }
+    const items = [];
+    for (const entry of raw) {
+      if (typeof entry !== "object" || entry === null) continue;
+      items.push(...await flattenItem(entry));
+    }
+    return { status: "read", items };
+  } catch (error) {
+    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);
+  }
+}
+function member(source, key) {
+  try {
+    return source[key];
+  } catch {
+    return void 0;
+  }
+}
+function readData(data, type) {
+  try {
+    const getData = member(data, "getData");
+    if (typeof getData !== "function") return void 0;
+    const value = getData.call(data, type);
+    return typeof value === "string" && value.length > 0 ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function filesFromItems(data) {
+  const files = [];
+  try {
+    const list = member(data, "items");
+    if (typeof list !== "object" || list === null) return files;
+    const length = member(list, "length");
+    if (typeof length !== "number") return files;
+    const items = list;
+    for (let index = 0; index < length; index++) {
+      try {
+        const item = items[index];
+        if (item === void 0 || item === null) continue;
+        if (item.kind !== "file" || typeof item.getAsFile !== "function") continue;
+        const file = item.getAsFile();
+        if (file !== null) files.push(file);
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+function filesFromFileList(data) {
+  const files = [];
+  try {
+    const list = member(data, "files");
+    if (typeof list !== "object" || list === null) return files;
+    const length = member(list, "length");
+    if (typeof length !== "number") return files;
+    const fileList = list;
+    for (let index = 0; index < length; index++) {
+      const file = fileList[index];
+      if (file !== void 0 && file !== null) files.push(file);
+    }
+  } catch {
+  }
+  return files;
+}
+function getPasteItems(event) {
+  const empty = { text: void 0, html: void 0, files: [] };
+  try {
+    if (typeof event !== "object" || event === null) return empty;
+    const transfer = member(event, "clipboardData");
+    if (typeof transfer !== "object" || transfer === null) return empty;
+    const data = transfer;
+    const fromItems = filesFromItems(data);
+    return {
+      text: readData(data, "text/plain"),
+      html: readData(data, "text/html"),
+      files: fromItems.length > 0 ? fromItems : filesFromFileList(data)
+    };
+  } catch {
+    return empty;
+  }
+}
+function usePasteHandler(handler, options) {
+  watchPostEffect((onCleanup) => {
+    if ((toValue(options?.enabled) ?? true) === false) return;
+    const node = toValue(options?.target) ?? (typeof window === "undefined" ? null : window);
+    if (node === null || typeof node.addEventListener !== "function") return;
+    const preventDefault = toValue(options?.preventDefault) ?? false;
+    const listener = (event) => {
+      const pasteEvent = event;
+      if (preventDefault) {
+        try {
+          pasteEvent.preventDefault();
+        } catch {
+        }
+      }
+      try {
+        handler(getPasteItems(pasteEvent), pasteEvent);
+      } catch {
+      }
+    };
+    node.addEventListener("paste", listener);
+    onCleanup(() => node.removeEventListener("paste", listener));
+  });
+}
+const DefaultResetAfterMs = 2e3;
+function useClipboardCopy(options) {
+  const status = shallowRef("idle");
+  let timer = null;
+  let disposed = false;
+  function clearTimer() {
+    if (timer === null) return;
+    clearTimeout(timer);
+    timer = null;
+  }
+  onScopeDispose(() => {
+    disposed = true;
+    clearTimer();
+  });
+  const copy = async (text) => {
+    const result = await copyText(text, toValue(options));
+    if (disposed) return result;
+    clearTimer();
+    status.value = result.status;
+    const resetAfterMs = toValue(options)?.resetAfterMs ?? DefaultResetAfterMs;
+    if (resetAfterMs > 0) {
+      timer = setTimeout(() => {
+        timer = null;
+        status.value = "idle";
+      }, resetAfterMs);
+    }
+    return result;
+  };
+  const reset = () => {
+    clearTimer();
+    status.value = "idle";
+  };
+  return { status, copy, reset };
+}
+const PermissionNames = {
+  read: "clipboard-read",
+  write: "clipboard-write"
+};
+async function getClipboardPermission(mode) {
+  const name = PermissionNames[mode];
+  if (name === void 0) return "unsupported";
+  return queryPermission(name);
+}
+export {
+  canCopy,
+  canCopyItems,
+  canLegacyCopy,
+  canReadClipboard,
+  copyBlob,
+  copyItems,
+  copyText,
+  getClipboardPermission,
+  getPasteItems,
+  legacyCopyText,
+  readItems,
+  readText,
+  useClipboardCopy,
+  usePasteHandler
+};
+//# sourceMappingURL=index.js.map