axokit-react 0.0.1

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Aakarsh Chaudhary
+
+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 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,121 @@
+# AxoKit — AsyncButton & useAsyncAction
+
+A tiny headless React UI primitive for handling asynchronous button states.
+
+Package name: `@axokit/react` (install with `npm install @axokit/react`).
+
+## Features
+
+- Automatic loading / success / error states
+- Hook (`useAsyncAction`) and headless component
+- TypeScript support
+- Minimal styles; load your own CSS or Tailwind classes
+- Works with React 18+
+
+## Installation
+
+```bash
+npm install @axokit/react
+# also install peer dependencies
+npm install react react-dom
+```
+
+## Usage (component)
+
+```tsx
+import { AsyncButton } from '@axokit/react';
+
+function SaveButton() {
+  const save = () => fetch('/api/save', { method: 'POST' });
+
+  return (
+    <AsyncButton
+      onAction={save}
+      loadingText="Saving..."
+      successText="Saved ✓"
+      errorText="Try again"
+      disableOnSuccess={false} // optional
+      className="px-4 py-2 rounded bg-blue-600 text-white"
+    >
+      Save
+    </AsyncButton>
+  );
+}
+```
+
+## Usage (hook)
+
+```tsx
+import { useAsyncAction } from '@axokit/react';
+
+function HookExample() {
+  const save = () => fetch('/api/save', { method: 'POST' });
+  const { state, trigger, reset } = useAsyncAction(save);
+
+  return (
+    <div>
+      <button onClick={trigger} disabled={state === 'loading'}>
+        {state === 'loading' ? 'Saving…' : state === 'success' ? 'Saved' : 'Save'}
+      </button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
+## API
+
+### `AsyncButton(props)`
+
+- `onAction: () => Promise<any>` — **required**.
+- `loadingText?: string` — default: `"Loading..."`.
+- `successText?: string` — default: `"Done!"`.
+- `errorText?: string` — default: `"Try again"`.
+- `successDuration?: number` — default: `1200` ms.
+- `errorDuration?: number` — default: `3000` ms.
+- `disableOnSuccess?: boolean` — default: `true`.
+- `onSuccess?: () => void`.
+- `onActionError?: (error: Error) => void`.
+- All other native `button` props are forwarded.
+
+### `useAsyncAction(action, options?)`
+
+Returns `{ state, error, trigger, reset }` with state `'idle'|'loading'|'success'|'error'`.
+
+## Accessibility
+
+- Button sets `aria-busy` while loading.
+- Exposes `data-state` attribute for styling.
+- The hook returns state for building your own live regions.
+
+## Styling
+
+Use `data-state` to adjust styles via CSS/Tailwind.
+
+```css
+.btn { @apply px-4 py-2 rounded; }
+.btn[data-state="loading"] { opacity: 0.7; }
+.btn[data-state="success"] { background-color: theme(colors.green.600); }
+.btn[data-state="error"] { background-color: theme(colors.red.600); }
+```
+
+## License
+
+MIT
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+
+type AsyncState = 'idle' | 'loading' | 'success' | 'error';
+interface UseAsyncActionOptions {
+    successDuration?: number;
+    errorDuration?: number;
+    onSuccess?: () => void;
+    onActionError?: (error: Error) => void;
+}
+interface UseAsyncActionReturn {
+    state: AsyncState;
+    error: Error | null;
+    trigger: () => Promise<void>;
+    reset: () => void;
+}
+declare function useAsyncAction(action: () => Promise<any>, options?: UseAsyncActionOptions): UseAsyncActionReturn;
+interface AsyncButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    onAction: () => Promise<any>;
+    loadingText?: string;
+    successText?: string;
+    errorText?: string;
+    successDuration?: number;
+    errorDuration?: number;
+    onSuccess?: () => void;
+    onActionError?: (error: Error) => void;
+    disableOnSuccess?: boolean;
+    children: React.ReactNode;
+}
+declare function AsyncButton({ onAction, loadingText, successText, errorText, successDuration, errorDuration, onSuccess, onActionError, disableOnSuccess, children, disabled, className, ...props }: AsyncButtonProps): react_jsx_runtime.JSX.Element;
+
+export { AsyncButton, useAsyncAction };

package/dist/index.js

@@ -0,0 +1,155 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AsyncButton: () => AsyncButton,
+  useAsyncAction: () => useAsyncAction
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/AsyncButton.tsx
+var React = __toESM(require("react"));
+var import_jsx_runtime = require("react/jsx-runtime");
+function useAsyncAction(action, options = {}) {
+  const { successDuration = 1200, errorDuration = 3e3, onSuccess, onActionError } = options;
+  const [state, setState] = React.useState("idle");
+  const [error, setError] = React.useState(null);
+  const timeoutRef = React.useRef(null);
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    return () => {
+      mountedRef.current = false;
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+  const reset = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    if (!mountedRef.current)
+      return;
+    setState("idle");
+    setError(null);
+  };
+  const trigger = async () => {
+    if (state === "loading")
+      return;
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    if (mountedRef.current) {
+      setState("loading");
+      setError(null);
+    }
+    try {
+      await action();
+      if (!mountedRef.current)
+        return;
+      setState("success");
+      onSuccess?.();
+      timeoutRef.current = setTimeout(() => {
+        if (mountedRef.current)
+          setState("idle");
+      }, successDuration);
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Action failed");
+      if (mountedRef.current) {
+        setError(error2);
+        setState("error");
+        onActionError?.(error2);
+      }
+      timeoutRef.current = setTimeout(() => {
+        if (mountedRef.current)
+          setState("idle");
+      }, errorDuration);
+    }
+  };
+  return { state, error, trigger, reset };
+}
+function AsyncButton({
+  onAction,
+  loadingText = "Loading...",
+  successText = "Done!",
+  errorText = "Try again",
+  successDuration = 1200,
+  errorDuration = 3e3,
+  onSuccess,
+  onActionError,
+  disableOnSuccess = true,
+  children,
+  disabled,
+  className = "",
+  ...props
+}) {
+  const { state, trigger } = useAsyncAction(onAction, {
+    successDuration,
+    errorDuration,
+    onSuccess,
+    onActionError
+  });
+  const getLabel = () => {
+    switch (state) {
+      case "loading":
+        return loadingText;
+      case "success":
+        return successText;
+      case "error":
+        return errorText;
+      default:
+        return children;
+    }
+  };
+  const isDisabled = disabled || state === "loading" || state === "success" && disableOnSuccess;
+  const { onClick: _nativeOnClick, type: buttonType = "button", ...rest } = props;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "button",
+    {
+      type: buttonType,
+      ...rest,
+      className,
+      onClick: trigger,
+      disabled: isDisabled,
+      "aria-busy": state === "loading",
+      "data-state": state,
+      children: getLabel()
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncButton,
+  useAsyncAction
+});

package/dist/index.mjs

@@ -0,0 +1,117 @@
+// src/AsyncButton.tsx
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+function useAsyncAction(action, options = {}) {
+  const { successDuration = 1200, errorDuration = 3e3, onSuccess, onActionError } = options;
+  const [state, setState] = React.useState("idle");
+  const [error, setError] = React.useState(null);
+  const timeoutRef = React.useRef(null);
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    return () => {
+      mountedRef.current = false;
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+  const reset = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    if (!mountedRef.current)
+      return;
+    setState("idle");
+    setError(null);
+  };
+  const trigger = async () => {
+    if (state === "loading")
+      return;
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    if (mountedRef.current) {
+      setState("loading");
+      setError(null);
+    }
+    try {
+      await action();
+      if (!mountedRef.current)
+        return;
+      setState("success");
+      onSuccess?.();
+      timeoutRef.current = setTimeout(() => {
+        if (mountedRef.current)
+          setState("idle");
+      }, successDuration);
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Action failed");
+      if (mountedRef.current) {
+        setError(error2);
+        setState("error");
+        onActionError?.(error2);
+      }
+      timeoutRef.current = setTimeout(() => {
+        if (mountedRef.current)
+          setState("idle");
+      }, errorDuration);
+    }
+  };
+  return { state, error, trigger, reset };
+}
+function AsyncButton({
+  onAction,
+  loadingText = "Loading...",
+  successText = "Done!",
+  errorText = "Try again",
+  successDuration = 1200,
+  errorDuration = 3e3,
+  onSuccess,
+  onActionError,
+  disableOnSuccess = true,
+  children,
+  disabled,
+  className = "",
+  ...props
+}) {
+  const { state, trigger } = useAsyncAction(onAction, {
+    successDuration,
+    errorDuration,
+    onSuccess,
+    onActionError
+  });
+  const getLabel = () => {
+    switch (state) {
+      case "loading":
+        return loadingText;
+      case "success":
+        return successText;
+      case "error":
+        return errorText;
+      default:
+        return children;
+    }
+  };
+  const isDisabled = disabled || state === "loading" || state === "success" && disableOnSuccess;
+  const { onClick: _nativeOnClick, type: buttonType = "button", ...rest } = props;
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: buttonType,
+      ...rest,
+      className,
+      onClick: trigger,
+      disabled: isDisabled,
+      "aria-busy": state === "loading",
+      "data-state": state,
+      children: getLabel()
+    }
+  );
+}
+export {
+  AsyncButton,
+  useAsyncAction
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "axokit-react",
+  "version": "0.0.1",
+  "description": "Headless async button and hook for React",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "author": "Aakarsh Chaudhary <aakarsh0219@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "tsup": "^6.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format cjs,esm --clean",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,json,md}\"",
+    "prepare": "npm run build"
+  }
+}