react-kofi-overlay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Harrison Liddiard
+
+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,91 @@
+# Ko-fi overlay widget
+
+[**Jump to usage**](#usage)
+
+React component for accepting donations though Ko-fi without leaving your website:
+
+
+
+## Features
+
+- Fully customize donate button style & content
+- Accept donations in page context (no redirect)
+- Customize donation panel size & placement
+- Trigger a function when donation panel is open or closed
+
+## Motivation
+
+To set up what Ko-fi calls their "[Floating Button Donation Widget](https://ko-fi.com/Manage/donation-widget-setup)," they let you do some basic customization and ask you to copy and paste two `<script>` tags onto your site:
+
+![Ko-fi donation widget setup](img/kofi_donation_widget_setup.png)
+
+This has some limitations:
+
+- It only allows you to choose from a handful of button calls-to-action, which may not meet your needs.
+- It provides a limited selection of background color choices, which may not match your website theme.
+- It requires you to load a `<script>` tag from their CDN, which creates a global variable, and you then need to call a method on that global to render the donate button. Few potential issues with that:
+  - Requires an extra network request on every page load.
+  - Doesn't work well with modern JS bundling + import/export systems like Webpack.
+  - Doesn't work well with a React component-based frontend.
+  - Doesn't play nice with web frameworks like Next.js. Next.js makes it difficult to inject an arbitrary script like `kofiWidgetOverlay.draw(...)` – and to only run that code after the external `overlay-widget.js` script is loaded.
+
+This component is designed to address those limitations.
+
+## Installation
+
+```bash
+npm install react-kofi-overlay
+```
+
+(or equivalent on your package manager)
+
+## Usage
+
+### Example
+
+```jsx
+import { Donate } from 'react-kofi-overlay'
+
+<Donate
+  username="liddiard"
+  classNames={{
+    donateBtn: 'myDonateButton',
+    profileLink: 'myProfileLink'
+  }}
+  styles={{
+    panel: { marginRight: '4em' }
+  }}
+  onToggle={(open) => {
+    console.log(`Donate panel ${open ? 'opened' : 'closed'}`)
+  }}
+>
+  ❤️ Support Me
+</Donate>
+```
+
+### Props
+
+| Prop name | Required | Type | Description |
+| ------------- | ------------- | ------------- | ------------- |
+| `username` | required | string | Ko-fi profile to display in the donation panel. Corresponds to the Ko-fi page at ko-fi.com/<username> |
+| (children) | required | ReactNode | Contents of the donation button. Can be plain text or any React nodes that are valid children of a `<button>` element. |
+| `classNames` | optional | object | Class names to apply to different parts of the component for styling. See [Styling](#styling) below for more info. |
+| `styles` | optional | object | Inline styles to apply to different parts of the component for styling. See [Styling](#styling) below for more info. |
+| `onToggle` | optional | function | Function to call when the donate panel is opened or closed. It receives one argument: a boolean `open` value that indicates if the panel was opened or closed. |
+
+### Styling
+
+The component accepts `classNames` or `styles` props to customize the appearance of the donate button and various parts of the donate panel. Both props should be an object with one or more of the keys below.
+
+Note: While you could provide both `classNames` and `styles`, it isn't recommended because they will override one another. Pick one based on how you're writing CSS in your codebase.
+
+| Name  | Description |
+| ------------- | ------------- |
+| `donateBtn` | Donate button – a <button> element. |
+| `panel` | Panel wrapper that popus up when donate button is clicked. By default, the panel is anchored to the bottom right of the viewport on desktop and full screen on mobile. |
+| `closeBtn` | Button to close the donate panel. |
+| `closeIcon` | (X) icon within the panel close button. |
+| `profileLink` | Link to your Ko-fi profile. By default, it's anchored to the bottom of the donate panel. |
+
+
+## Development

package/dist/Donate.d.ts

@@ -0,0 +1,56 @@
+import React, { CSSProperties } from 'react';
+export interface StyleDefs<T> {
+    /**
+     * Popup wrapper. By default, the popup is anchored to the bottom right of
+     * the viewport on desktop and full screen on mobile.
+     */
+    popup?: T;
+    /**
+     * Donate button.
+     */
+    donateBtn?: T;
+    /**
+     * Button to close the donate popup.
+     */
+    closeBtn?: T;
+    /**
+     * (X) icon within the popup close button.
+     */
+    closeIcon?: T;
+    /**
+     * Link to your Ko-fi profile. By default, it's anchored to the bottom of the donate popup.
+     */
+    profileLink?: T;
+}
+export interface DonateProps {
+    /**
+     * Child nodes of the donate button. E.g., "Support me on Ko-fi"
+     */
+    children: React.ReactNode;
+    /**
+     * Your Ko-fi profile name. (ko-fi.com/[username])
+     */
+    username: string;
+    /**
+     * Optional custom class names to apply to the component.
+     */
+    classNames?: StyleDefs<string>;
+    /**
+     * Optional custom styles to apply to the component.
+     */
+    styles?: StyleDefs<CSSProperties>;
+    /**
+     * Optional function to be called when the donation form is opened or closed.
+     */
+    onToggle?: (open: boolean) => void;
+}
+/**
+ * Component to display a button that opens a Ko-fi donation popup when clicked.
+ *
+ * @component
+ * @example
+ * <Donate username="liddiard">
+ *   Support My Work
+ * </Donate>
+ */
+export default function Donate({ children, username, classNames, styles, onToggle }: DonateProps): React.JSX.Element;

package/dist/Donate.js

@@ -0,0 +1,70 @@
+'use client';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = __importStar(require("react"));
+var classnames_1 = __importDefault(require("classnames"));
+var Donate_module_scss_1 = __importDefault(require("./Donate.module.scss"));
+var react_icons_1 = require("react-icons");
+var bs_1 = require("react-icons/bs");
+/**
+ * Component to display a button that opens a Ko-fi donation popup when clicked.
+ *
+ * @component
+ * @example
+ * <Donate username="liddiard">
+ *   Support My Work
+ * </Donate>
+ */
+function Donate(_a) {
+    var children = _a.children, username = _a.username, _b = _a.classNames, classNames = _b === void 0 ? {} : _b, _c = _a.styles, styles = _c === void 0 ? {} : _c, _d = _a.onToggle, onToggle = _d === void 0 ? function () { } : _d;
+    var baseUrl = "https://ko-fi.com/".concat(username);
+    var _e = (0, react_1.useState)(false), open = _e[0], setOpen = _e[1];
+    var handleOpen = function (isOpen) {
+        setOpen(isOpen);
+        onToggle(isOpen);
+    };
+    return (react_1.default.createElement(react_1.default.Fragment, null,
+        react_1.default.createElement("button", { className: (0, classnames_1.default)(Donate_module_scss_1.default.donateBtn, classNames.donateBtn), style: styles.donateBtn, onClick: function () { return handleOpen(true); } }, children),
+        open ?
+            react_1.default.createElement("div", { className: (0, classnames_1.default)(Donate_module_scss_1.default.popup, classNames.popup), style: styles.popup },
+                react_1.default.createElement("button", { className: (0, classnames_1.default)(Donate_module_scss_1.default.closeBtn, classNames.closeBtn), style: styles.closeBtn, onClick: function () { return handleOpen(false); } },
+                    react_1.default.createElement(react_icons_1.IconContext.Provider, { value: {
+                            className: (0, classnames_1.default)(Donate_module_scss_1.default.closeIcon, classNames.closeIcon),
+                            style: styles.closeIcon
+                        } },
+                        react_1.default.createElement(bs_1.BsX, { title: "Close" }))),
+                react_1.default.createElement("iframe", { src: "".concat(baseUrl, "?hidefeed=true&widget=true&embed=true") }),
+                react_1.default.createElement("div", { className: (0, classnames_1.default)(Donate_module_scss_1.default.profileLink, classNames.profileLink), style: styles.profileLink },
+                    react_1.default.createElement("a", { href: baseUrl, target: "_blank", rel: "noreferrer" },
+                        "ko-fi.com/",
+                        username)))
+            : null));
+}
+exports.default = Donate;
+//# sourceMappingURL=Donate.js.map

package/dist/Donate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Donate.js","sourceRoot":"","sources":["../src/Donate.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEZ,6CAAsD;AACtD,0DAAgC;AAEhC,4EAAoC;AACpC,2CAAyC;AACzC,qCAAiD;AAkDjD;;;;;;;;GAQG;AACH,SAAwB,MAAM,CAAC,EAMjB;QALZ,QAAQ,cAAA,EACR,QAAQ,cAAA,EACR,kBAAe,EAAf,UAAU,mBAAG,EAAE,KAAA,EACf,cAAW,EAAX,MAAM,mBAAG,EAAE,KAAA,EACX,gBAAmB,EAAnB,QAAQ,mBAAG,cAAO,CAAC,KAAA;IAEnB,IAAM,OAAO,GAAG,4BAAqB,QAAQ,CAAE,CAAA;IACzC,IAAA,KAAkB,IAAA,gBAAQ,EAAC,KAAK,CAAC,EAAhC,IAAI,QAAA,EAAE,OAAO,QAAmB,CAAA;IAEvC,IAAM,UAAU,GAAG,UAAC,MAAe;QACjC,OAAO,CAAC,MAAM,CAAC,CAAA;QACf,QAAQ,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC,CAAA;IAED,OAAO,CACL;QACE,0CACE,SAAS,EAAE,IAAA,oBAAO,EAAC,4BAAC,CAAC,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,EACrD,KAAK,EAAE,MAAM,CAAC,SAAS,EACvB,OAAO,EAAE,cAAM,OAAA,UAAU,CAAC,IAAI,CAAC,EAAhB,CAAgB,IAE9B,QAAQ,CACF;QACR,IAAI,CAAC,CAAC;YACL,uCACE,SAAS,EAAE,IAAA,oBAAO,EAAC,4BAAC,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,EAC7C,KAAK,EAAE,MAAM,CAAC,KAAK;gBAEnB,0CACE,SAAS,EAAE,IAAA,oBAAO,EAAC,4BAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,EACnD,KAAK,EAAE,MAAM,CAAC,QAAQ,EACtB,OAAO,EAAE,cAAM,OAAA,UAAU,CAAC,KAAK,CAAC,EAAjB,CAAiB;oBAEhC,8BAAC,yBAAW,CAAC,QAAQ,IAAC,KAAK,EAAE;4BAC3B,SAAS,EAAE,IAAA,oBAAO,EAAC,4BAAC,CAAC,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC;4BACrD,KAAK,EAAE,MAAM,CAAC,SAAS;yBACxB;wBACC,8BAAC,QAAS,IAAC,KAAK,EAAC,OAAO,GAAG,CACN,CAChB;gBACT,0CAAQ,GAAG,EAAE,UAAG,OAAO,0CAAuC,GAAI;gBAClE,uCACE,SAAS,EAAE,IAAA,oBAAO,EAAC,4BAAC,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,EACzD,KAAK,EAAE,MAAM,CAAC,WAAW;oBAEzB,qCAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAC,QAAQ,EAAC,GAAG,EAAC,YAAY;;wBACrC,QAAQ,CACjB,CACA,CACF;YACR,CAAC,CAAC,IAAI,CACL,CACJ,CAAA;AACH,CAAC;AAtDD,yBAsDC"}