@ailuracode/alpine-export 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ailuracode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @ailuracode/alpine-export
+
+Programmatic file exports (browser downloads) for Alpine.js.
+
+**[Full documentation →](../../docs/export.md)**
+
+## Install
+
+```bash
+npm install @ailuracode/alpine-export alpinejs
+```
+
+## Quick example
+
+```js
+import Alpine from "alpinejs";
+import exportPlugin from "@ailuracode/alpine-export";
+
+Alpine.plugin(exportPlugin);
+Alpine.start();
+```
+
+```html
+<button @click="await $export('Hello world', 'hello.txt')">
+  Export text
+</button>
+
+<button @click="await $export('/assets/report.pdf', 'report.pdf')">
+  Export file
+</button>
+```
+
+## API summary
+
+| | |
+|-|-|
+| **Magic** | `$export(source, options?)` |
+| **Helpers** | `$export.isSupported()` |
+
+Callable like `$clipboard` and `$share`.
+
+## License
+
+MIT

package/dist/global.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="@types/alpinejs" />
+
+export type { ExportMagic } from "./index.js";
+
+declare global {
+  namespace Alpine {
+    interface Magics<T> {
+      $export: import("./index.js").ExportMagic;
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import AlpineType from 'alpinejs';
+
+type ExportOptions = {
+    filename?: string;
+    mimeType?: string;
+};
+type ExportSource = string | Blob | File;
+type ExportMagic = ((source: ExportSource, options?: ExportOptions | string) => Promise<boolean>) & {
+    isSupported(): boolean;
+};
+/** Returns whether programmatic file exports are available in this environment. */
+declare function isExportSupported(): boolean;
+/** Exports a URL, blob, file, or text payload as a download. Resolves to `true` on success. Never throws. */
+declare function exportData(source: ExportSource, options?: ExportOptions | string): Promise<boolean>;
+/** Builds callable `$export` magic with `isSupported` helper. */
+declare function createExportMagic(): ExportMagic;
+/** Alpine.js export plugin. Registers callable magic `$export`. */
+declare function exportPlugin(Alpine: AlpineType.Alpine): void;
+declare global {
+    namespace Alpine {
+        interface Magics<T> {
+            $export: ExportMagic;
+        }
+    }
+}
+
+export { type ExportMagic, type ExportOptions, type ExportSource, createExportMagic, exportPlugin as default, exportData, isExportSupported };

package/dist/index.js

@@ -0,0 +1,84 @@
+// src/index.ts
+var URL_LIKE = /^(https?:|data:|blob:|\/|\.\/|\.\.\/)/i;
+function normalizeOptions(options) {
+  if (typeof options === "string") {
+    return { filename: options };
+  }
+  return options ?? {};
+}
+function isExportEnvironment() {
+  return typeof document !== "undefined" && typeof document.createElement === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function";
+}
+function isExportSupported() {
+  return isExportEnvironment();
+}
+function triggerAnchorExport(href, filename) {
+  const anchor = document.createElement("a");
+  anchor.href = href;
+  anchor.rel = "noopener";
+  if (filename) {
+    anchor.download = filename;
+  }
+  anchor.style.display = "none";
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+}
+function revokeObjectUrlLater(url) {
+  setTimeout(() => {
+    URL.revokeObjectURL(url);
+  }, 0);
+}
+function exportBlob(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  try {
+    triggerAnchorExport(url, filename);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    revokeObjectUrlLater(url);
+  }
+}
+function isUrlLike(value) {
+  return URL_LIKE.test(value);
+}
+function exportData(source, options) {
+  if (!isExportSupported()) {
+    return Promise.resolve(false);
+  }
+  const { filename, mimeType } = normalizeOptions(options);
+  try {
+    if (source instanceof Blob) {
+      const name = filename ?? (source instanceof File ? source.name : "export");
+      return Promise.resolve(exportBlob(source, name));
+    }
+    const value = String(source);
+    if (isUrlLike(value)) {
+      triggerAnchorExport(value, filename);
+      return Promise.resolve(true);
+    }
+    if (!filename) {
+      return Promise.resolve(false);
+    }
+    const blob = new Blob([value], { type: mimeType ?? "text/plain;charset=utf-8" });
+    return Promise.resolve(exportBlob(blob, filename));
+  } catch {
+    return Promise.resolve(false);
+  }
+}
+function createExportMagic() {
+  const exportFile = (source, options) => exportData(source, options);
+  exportFile.isSupported = isExportSupported;
+  return exportFile;
+}
+function exportPlugin(Alpine) {
+  Alpine.magic("export", () => createExportMagic());
+}
+export {
+  createExportMagic,
+  exportPlugin as default,
+  exportData,
+  isExportSupported
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type AlpineType from \"alpinejs\";\n\nexport type ExportOptions = {\n  filename?: string;\n  mimeType?: string;\n};\n\nexport type ExportSource = string | Blob | File;\n\nexport type ExportMagic = ((\n  source: ExportSource,\n  options?: ExportOptions | string\n) => Promise<boolean>) & {\n  isSupported(): boolean;\n};\n\nconst URL_LIKE = /^(https?:|data:|blob:|\\/|\\.\\/|\\.\\.\\/)/i;\n\nfunction normalizeOptions(options?: ExportOptions | string): ExportOptions {\n  if (typeof options === \"string\") {\n    return { filename: options };\n  }\n\n  return options ?? {};\n}\n\nfunction isExportEnvironment(): boolean {\n  return (\n    typeof document !== \"undefined\" &&\n    typeof document.createElement === \"function\" &&\n    typeof URL !== \"undefined\" &&\n    typeof URL.createObjectURL === \"function\"\n  );\n}\n\n/** Returns whether programmatic file exports are available in this environment. */\nexport function isExportSupported(): boolean {\n  return isExportEnvironment();\n}\n\nfunction triggerAnchorExport(href: string, filename?: string): void {\n  const anchor = document.createElement(\"a\");\n  anchor.href = href;\n  anchor.rel = \"noopener\";\n\n  if (filename) {\n    anchor.download = filename;\n  }\n\n  anchor.style.display = \"none\";\n  document.body.appendChild(anchor);\n  anchor.click();\n  document.body.removeChild(anchor);\n}\n\nfunction revokeObjectUrlLater(url: string): void {\n  setTimeout(() => {\n    URL.revokeObjectURL(url);\n  }, 0);\n}\n\nfunction exportBlob(blob: Blob, filename: string): boolean {\n  const url = URL.createObjectURL(blob);\n\n  try {\n    triggerAnchorExport(url, filename);\n    return true;\n  } catch {\n    return false;\n  } finally {\n    revokeObjectUrlLater(url);\n  }\n}\n\nfunction isUrlLike(value: string): boolean {\n  return URL_LIKE.test(value);\n}\n\n/** Exports a URL, blob, file, or text payload as a download. Resolves to `true` on success. Never throws. */\nexport function exportData(\n  source: ExportSource,\n  options?: ExportOptions | string\n): Promise<boolean> {\n  if (!isExportSupported()) {\n    return Promise.resolve(false);\n  }\n\n  const { filename, mimeType } = normalizeOptions(options);\n\n  try {\n    if (source instanceof Blob) {\n      const name = filename ?? (source instanceof File ? source.name : \"export\");\n      return Promise.resolve(exportBlob(source, name));\n    }\n\n    const value = String(source);\n\n    if (isUrlLike(value)) {\n      triggerAnchorExport(value, filename);\n      return Promise.resolve(true);\n    }\n\n    if (!filename) {\n      return Promise.resolve(false);\n    }\n\n    const blob = new Blob([value], { type: mimeType ?? \"text/plain;charset=utf-8\" });\n    return Promise.resolve(exportBlob(blob, filename));\n  } catch {\n    return Promise.resolve(false);\n  }\n}\n\n/** Builds callable `$export` magic with `isSupported` helper. */\nexport function createExportMagic(): ExportMagic {\n  const exportFile = (source: ExportSource, options?: ExportOptions | string) =>\n    exportData(source, options);\n  exportFile.isSupported = isExportSupported;\n  return exportFile;\n}\n\n/** Alpine.js export plugin. Registers callable magic `$export`. */\nexport default function exportPlugin(Alpine: AlpineType.Alpine): void {\n  Alpine.magic(\"export\", () => createExportMagic());\n}\n\ndeclare global {\n  namespace Alpine {\n    interface Magics<T> {\n      $export: ExportMagic;\n    }\n  }\n}\n"],"mappings":";AAgBA,IAAM,WAAW;AAEjB,SAAS,iBAAiB,SAAiD;AACzE,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO,EAAE,UAAU,QAAQ;AAAA,EAC7B;AAEA,SAAO,WAAW,CAAC;AACrB;AAEA,SAAS,sBAA+B;AACtC,SACE,OAAO,aAAa,eACpB,OAAO,SAAS,kBAAkB,cAClC,OAAO,QAAQ,eACf,OAAO,IAAI,oBAAoB;AAEnC;AAGO,SAAS,oBAA6B;AAC3C,SAAO,oBAAoB;AAC7B;AAEA,SAAS,oBAAoB,MAAc,UAAyB;AAClE,QAAM,SAAS,SAAS,cAAc,GAAG;AACzC,SAAO,OAAO;AACd,SAAO,MAAM;AAEb,MAAI,UAAU;AACZ,WAAO,WAAW;AAAA,EACpB;AAEA,SAAO,MAAM,UAAU;AACvB,WAAS,KAAK,YAAY,MAAM;AAChC,SAAO,MAAM;AACb,WAAS,KAAK,YAAY,MAAM;AAClC;AAEA,SAAS,qBAAqB,KAAmB;AAC/C,aAAW,MAAM;AACf,QAAI,gBAAgB,GAAG;AAAA,EACzB,GAAG,CAAC;AACN;AAEA,SAAS,WAAW,MAAY,UAA2B;AACzD,QAAM,MAAM,IAAI,gBAAgB,IAAI;AAEpC,MAAI;AACF,wBAAoB,KAAK,QAAQ;AACjC,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT,UAAE;AACA,yBAAqB,GAAG;AAAA,EAC1B;AACF;AAEA,SAAS,UAAU,OAAwB;AACzC,SAAO,SAAS,KAAK,KAAK;AAC5B;AAGO,SAAS,WACd,QACA,SACkB;AAClB,MAAI,CAAC,kBAAkB,GAAG;AACxB,WAAO,QAAQ,QAAQ,KAAK;AAAA,EAC9B;AAEA,QAAM,EAAE,UAAU,SAAS,IAAI,iBAAiB,OAAO;AAEvD,MAAI;AACF,QAAI,kBAAkB,MAAM;AAC1B,YAAM,OAAO,aAAa,kBAAkB,OAAO,OAAO,OAAO;AACjE,aAAO,QAAQ,QAAQ,WAAW,QAAQ,IAAI,CAAC;AAAA,IACjD;AAEA,UAAM,QAAQ,OAAO,MAAM;AAE3B,QAAI,UAAU,KAAK,GAAG;AACpB,0BAAoB,OAAO,QAAQ;AACnC,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B;AAEA,QAAI,CAAC,UAAU;AACb,aAAO,QAAQ,QAAQ,KAAK;AAAA,IAC9B;AAEA,UAAM,OAAO,IAAI,KAAK,CAAC,KAAK,GAAG,EAAE,MAAM,YAAY,2BAA2B,CAAC;AAC/E,WAAO,QAAQ,QAAQ,WAAW,MAAM,QAAQ,CAAC;AAAA,EACnD,QAAQ;AACN,WAAO,QAAQ,QAAQ,KAAK;AAAA,EAC9B;AACF;AAGO,SAAS,oBAAiC;AAC/C,QAAM,aAAa,CAAC,QAAsB,YACxC,WAAW,QAAQ,OAAO;AAC5B,aAAW,cAAc;AACzB,SAAO;AACT;AAGe,SAAR,aAA8B,QAAiC;AACpE,SAAO,MAAM,UAAU,MAAM,kBAAkB,CAAC;AAClD;","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ailuracode/alpine-export",
+  "version": "0.1.0",
+  "description": "Alpine.js file export magic",
+  "type": "module",
+  "license": "MIT",
+  "author": "ailuracode",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ailuracode/alpine.git",
+    "directory": "packages/export"
+  },
+  "bugs": {
+    "url": "https://github.com/ailuracode/alpine/issues"
+  },
+  "homepage": "https://github.com/ailuracode/alpine/tree/master/packages/export#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./global": {
+      "types": "./dist/global.d.ts"
+    }
+  },
+  "types": "./dist/global.d.ts",
+  "peerDependencies": {
+    "alpinejs": "^3.0.0",
+    "@types/alpinejs": "^3.13.11"
+  },
+  "peerDependenciesMeta": {
+    "@types/alpinejs": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "alpinejs",
+    "alpine",
+    "plugin",
+    "export",
+    "file",
+    "download"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --sourcemap --out-dir dist && cp src/global.d.ts dist/global.d.ts",
+    "test": "vitest run --config ../../vitest.config.js test"
+  }
+}