@void-snippets/react 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @void-snippets/react
 
-TanStack Query v5 hook factory for React. Generates a fully-typed set of hooks (`useList`, `useGet`, `useMutations`, `useInfinite`) from a `ResourceService` instance — with zero manual type annotations required.
+TanStack Query v5 resource hooks factory + general-purpose React hooks. All fully typed, zero boilerplate.
 
 ## Installation
 
@@ -10,119 +10,87 @@ npm install @void-snippets/react @void-snippets/client @tanstack/react-query axi
 
 ---
 
-## Quick Start
+## Setup
 
-### 1. Configure axios once at your app entry point
+### Configure axios once
 
 ```ts
-// src/main.ts
 import axios from 'axios';
 import { configure } from '@void-snippets/client';
-
-const axiosInstance = axios.create({ baseURL: 'https://api.example.com' });
-configure(axiosInstance);
+configure(axios.create({ baseURL: 'https://api.example.com' }));
 ```
 
-### 2. Set up TanStack Query
+### Wrap your app with QueryClientProvider
 
 ```tsx
-// src/main.tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
 const queryClient = new QueryClient();
-
 function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-    </QueryClientProvider>
-  );
+  return <QueryClientProvider client={queryClient}><YourApp /></QueryClientProvider>;
 }
 ```
 
-### 3. Define a resource service
+---
 
-```ts
-// contacts/contacts.api.ts
-import { ResourceService } from '@void-snippets/client';
-import type { Contact } from './contacts.types';
+## Resource Hooks — `createResourceHooks`
 
+Define a service once, get all hooks free — fully typed, no generics needed.
+
+```ts
+// contacts.api.ts
 export class ContactsApiService extends ResourceService<
-  Contact.Id,
-  Contact.Base,
-  Contact.WithCreatedBy,
-  Contact.Apis.CreatePayload,
-  Contact.Apis.UpdatePayload
+  Contact.Id, Contact.Base, Contact.WithCreatedBy,
+  Contact.Apis.CreatePayload, Contact.Apis.UpdatePayload
 > {
-  constructor() {
-    super('/contacts');
-  }
+  constructor() { super('/contacts'); }
 }
-
 export const ContactsApis = new ContactsApiService();
-```
 
-### 4. Create hooks
-
-```ts
-// contacts/contacts.hooks.ts
-import { createResourceHooks } from '@void-snippets/react';
-import { ContactsApis } from './contacts.api';
-
-// All types are inferred from ContactsApis — no generics needed
+// contacts.hooks.ts
 export const contactHooks = createResourceHooks('contacts', ContactsApis);
 ```
 
-### 5. Use in components
+### `useList(params?)`
 
 ```tsx
-// List with pagination
-function ContactsList() {
-  const { contacts, isContactsLoading, pagination } = contactHooks.useList({
-    page: 1,
-    limit: 20,
-  });
-
-  if (isContactsLoading) return <Spinner />;
-  return contacts.map(c => <ContactCard key={c._id} contact={c} />);
-}
-
-// Single item
-function ContactDetail({ id }: { id: Contact.Id }) {
-  const { data, isLoading } = contactHooks.useGet(id);
-  // data is typed as Contact.WithCreatedBy ✅
-}
+const { list, isLoading, pagination, error, invalidate } =
+  contactHooks.useList({ page: 1, limit: 20 });
+// list is typed as Contact.Base[] ✅
+```
 
-// Mutations (auto-invalidate the list on success)
-function CreateContactForm() {
-  const { create, update, delete: remove } = contactHooks.useMutations();
+| Key | Type |
+|---|---|
+| `list` | `TBase[]` |
+| `pagination` | `VSPagination` |
+| `isLoading` | `boolean` |
+| `error` | `Error \| null` |
+| `invalidate` | `() => void` |
 
-  return (
-    <button onClick={() => create.mutate({ name: 'John' })}>
-      Create
-    </button>
-  );
-}
+### `useGet(id, staleTime?)`
 
-// Infinite scroll
-function InfiniteContactsList() {
-  const { data, fetchNextPage, hasNextPage } = contactHooks.useInfinite({ limit: 20 });
-  const all = data?.pages.flatMap(p => p.items) ?? [];
-}
+```tsx
+const { item, isLoading, error, refetch } = contactHooks.useGet(id);
+// item is typed as Contact.WithCreatedBy ✅
 ```
 
----
+### `useMutations()`
+
+```tsx
+const { create, update, remove } = contactHooks.useMutations();
 
-## Custom API Response Shapes
+create.mutate({ name: 'John' });
+update.mutate({ _id: id, payload: { name: 'Jane' } });
+remove.mutate(id);
+```
 
-By default the library expects this shape from your API:
+### `useInfinite(params?)`
 
-```json
-// List:   { "data": { "items": [], "page": 1, "limit": 10, "totalPages": 5, "totalDocuments": 42 } }
-// Single: { "data": { "_id": "...", "name": "..." } }
+```tsx
+const { data, fetchNextPage, hasNextPage } = contactHooks.useInfinite({ limit: 20 });
+const all = data?.pages.flatMap(p => p.items) ?? [];
 ```
 
-If your API looks different, pass adapters as a third argument:
+### Custom API shapes
 
 ```ts
 export const contactHooks = createResourceHooks('contacts', ContactsApis, {
@@ -143,25 +111,71 @@ export const contactHooks = createResourceHooks('contacts', ContactsApis, {
 
 ---
 
-## Hook Reference
+## General-Purpose Hooks
 
-### `useList(params?)`
-| Returned key | Type | Description |
-|---|---|---|
-| `[prefix]` | `TBase[]` | e.g. `contacts` for prefix `"contacts"` |
-| `pagination` | `TPagination` | `{ page, limit, totalPages, totalDocuments }` |
-| `is[Prefix]Loading` | `boolean` | e.g. `isContactsLoading` |
-| `[prefix]Error` | `Error \| null` | e.g. `contactsError` |
-| `invalidate[Prefix]` | `() => void` | e.g. `invalidateContacts` |
+### `useAlertMessage(autoHideDuration?)`
 
-### `useGet(id, staleTime?)`
-Returns `{ data, isLoading, error, refetch }`. Skips the query if `id` is empty.
+```tsx
+const { alert, showAlert, hideAlert } = useAlertMessage(3000);
 
-### `useMutations()`
-Returns `{ create, update, delete }` — each is a TanStack `UseMutationResult`. All auto-invalidate the list cache on success.
+showAlert('Saved!', 'success');
+showAlert('Something went wrong', 'error');
+showAlert(<b>Custom JSX</b>, 'info');
+// alert.isVisible, alert.message, alert.type
+```
 
-### `useInfinite(params?)`
-Returns the standard TanStack `useInfiniteQuery` result with `items` and `pagination` per page.
+Variants: `"success" | "info" | "error"`
+
+---
+
+### `useAsyncState<T>(initialData?)`
+
+```tsx
+const { data, isLoading, isError, execute } = useAsyncState<User>();
+
+const [err, user] = await execute(() => fetchUser(id), {
+  onSuccess: (u) => showAlert(`Welcome ${u.name}`, 'success'),
+  onError: (e) => showAlert(e.message, 'error'),
+});
+```
+
+Status values: `"idle" | "pending" | "success" | "error"`
+
+---
+
+### `useCallTimer(startedAt?)`
+
+```tsx
+const duration = useCallTimer(call.startedAt); // "02:45"
+const duration = useCallTimer(null);           // "00:00"
+```
+
+---
+
+### `useModal<T>()`
+
+```tsx
+const modal = useModal<Contact.Base>();
+
+modal.openCreateModal();      // data → null
+modal.openEditModal(contact); // data → contact
+
+if (modal.data) { /* edit mode */ } else { /* create mode */ }
+```
+
+---
+
+### `usePagination(initialPage?, initialLimit?)`
+
+```tsx
+const { queryParams, onPaginationChange } = usePagination(1, 20);
+
+// Wire directly to useList
+const { list } = contactHooks.useList(queryParams);
+
+// Wire to your pagination UI
+<Pagination onChange={onPaginationChange} total={pagination.totalDocuments} />
+```
 
 ---
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { ResourceAdapters, TQueryParams, TPagination, ResourceListResult } from '@void-snippets/core';
+import { VSAdapters, VSQueryParams, VSPagination, VSListResult } from '@void-snippets/core';
+import { ReactNode } from 'react';
 
-type CapitalizeStr<S extends string> = S extends `${infer F}${infer Rest}` ? `${Uppercase<F>}${Rest}` : S;
 interface WithResourceTypes {
     readonly __types: {
         id: unknown;
@@ -20,21 +20,23 @@ type Create<S extends WithResourceTypes> = S["__types"]["create"];
 type Update<S extends WithResourceTypes> = S["__types"]["update"];
 type ListRaw<S extends WithResourceTypes> = S["__types"]["listRaw"];
 type SingleRaw<S extends WithResourceTypes> = S["__types"]["singleRaw"];
-type UseListReturn<K extends string, TBase> = {
-    [P in K]: TBase[];
-} & {
-    pagination: TPagination;
-} & {
-    [P in `is${CapitalizeStr<K>}Loading`]: boolean;
-} & {
-    [P in `${K}Error`]: Error | null;
-} & {
-    [P in `invalidate${CapitalizeStr<K>}`]: () => void;
-};
-interface CreateResourceHooksOptions<TListRaw, TBase, TSingleRaw, TDetail> {
+interface VSUseListReturn<TBase> {
+    list: TBase[];
+    pagination: VSPagination;
+    isLoading: boolean;
+    error: Error | null;
+    invalidate: () => void;
+}
+interface VSUseGetReturn<TDetail> {
+    item: TDetail | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+interface VSResourceHooksOptions<TListRaw, TBase, TSingleRaw, TDetail> {
     /**
-     * Adapters map your API's raw response shapes to the library's internal
-     * format. Omit this entirely if your API matches the default shape:
+     * Adapters map your API's raw response to the library's internal format.
+     * Omit if your API matches the default shape:
      * List:   { data: { items, page, limit, totalPages, totalDocuments } }
      * Single: { data: <item> }
      *
@@ -54,54 +56,186 @@ interface CreateResourceHooksOptions<TListRaw, TBase, TSingleRaw, TDetail> {
      *   },
      * })
      */
-    adapters?: ResourceAdapters<TListRaw, TBase, TSingleRaw, TDetail>;
+    adapters?: VSAdapters<TListRaw, TBase, TSingleRaw, TDetail>;
     /**
      * Default params passed to useList and useInfinite when none are provided.
      * @default { page: 1, limit: 10 }
      */
-    defaultParams?: TQueryParams;
+    defaultParams?: VSQueryParams;
 }
 /**
  * Creates a set of TanStack Query hooks for a resource.
- * All types are fully inferred from the `apiService` instance — no generics
- * need to be passed manually.
+ * All types are fully inferred from the `apiService` instance — no generics needed.
  *
- * @param queryKeyPrefix  - TanStack Query cache key prefix and the base name
- *                          for the returned hook properties.
- *                          e.g. "contacts" → { contacts, isContactsLoading, ... }
+ * @param queryKeyPrefix  - TanStack Query cache key. Used to scope the cache
+ *                          and for auto-invalidation. e.g. "contacts"
  * @param apiService      - An instance of ResourceService (or a subclass).
  * @param options         - Optional adapters and default params.
  *
  * @example
- * // contacts.hooks.ts
- * import { createResourceHooks } from '@void-snippets/react';
- * import { ContactsApis } from './contacts.api';
- *
- * // No generics needed — all types are inferred from ContactsApis
  * export const contactHooks = createResourceHooks('contacts', ContactsApis);
  *
- * // In a component:
- * const { contacts, isContactsLoading } = contactHooks.useList();
- * const { data } = contactHooks.useGet(id);  // data: Contact.WithCreatedBy
- * const { create, update, delete: remove } = contactHooks.useMutations();
+ * // useList — generic fixed shape
+ * const { list, isLoading, pagination, error, invalidate } = contactHooks.useList();
+ * // list is typed as Contact.Base[] ✅
+ *
+ * // useGet
+ * const { item, isLoading, error, refetch } = contactHooks.useGet(id);
+ * // item is typed as Contact.WithCreatedBy ✅
+ *
+ * // useMutations
+ * const { create, update, remove } = contactHooks.useMutations();
  */
-declare function createResourceHooks<K extends string, S extends WithResourceTypes>(queryKeyPrefix: K, apiService: S, options?: CreateResourceHooksOptions<ListRaw<S>, Base<S>, SingleRaw<S>, Detail<S>>): {
-    useList: (params?: TQueryParams) => UseListReturn<K, Base<S>>;
-    useGet: (id: Id<S>, staleTime?: number) => {
-        data: _tanstack_react_query.NoInfer<Detail<S>> | undefined;
-        isLoading: boolean;
-        error: Error | null;
-        refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.NoInfer<Detail<S>>, Error>>;
-    };
+declare function createResourceHooks<K extends string, S extends WithResourceTypes>(queryKeyPrefix: K, apiService: S, options?: VSResourceHooksOptions<ListRaw<S>, Base<S>, SingleRaw<S>, Detail<S>>): {
+    useList: (params?: VSQueryParams) => VSUseListReturn<Base<S>>;
+    useGet: (id: Id<S>, staleTime?: number) => VSUseGetReturn<Detail<S>>;
     useMutations: () => {
         create: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Create<S>, unknown>;
         update: _tanstack_react_query.UseMutationResult<Detail<S>, Error, {
             _id: Id<S>;
             payload: Update<S>;
         }, unknown>;
-        delete: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Id<S>, unknown>;
+        remove: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Id<S>, unknown>;
     };
-    useInfinite: (params?: TQueryParams) => _tanstack_react_query.UseInfiniteQueryResult<_tanstack_react_query.InfiniteData<ResourceListResult<Base<S>>, unknown>, Error>;
+    useInfinite: (params?: VSQueryParams) => _tanstack_react_query.UseInfiniteQueryResult<_tanstack_react_query.InfiniteData<VSListResult<Base<S>>, unknown>, Error>;
 };
 
-export { type CreateResourceHooksOptions, type UseListReturn, createResourceHooks };
+type VSAlertVariant = "success" | "info" | "error";
+interface VSAlertState {
+    message: ReactNode | string;
+    type: VSAlertVariant;
+    isVisible: boolean;
+}
+/**
+ * Manages alert/toast message state with optional auto-hide.
+ *
+ * @param autoHideDuration - ms before alert hides automatically. Pass 0 to disable. Default: 3000
+ *
+ * @example
+ * const { alert, showAlert, hideAlert } = useAlertMessage();
+ * showAlert('Saved successfully!', 'success');
+ * showAlert(<b>Something went wrong</b>, 'error');
+ */
+declare function useAlertMessage(autoHideDuration?: number): {
+    alert: VSAlertState;
+    showAlert: (message: ReactNode | string, type?: VSAlertVariant) => void;
+    hideAlert: () => void;
+};
+
+type VSAsyncStatus = "idle" | "pending" | "success" | "error";
+interface VSAsyncState<T> {
+    data: T | null;
+    status: VSAsyncStatus;
+    error: Error | null;
+}
+interface VSUseAsyncStateReturn<T> extends VSAsyncState<T> {
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    setData: (data: T | null) => void;
+    setError: (error: Error | null) => void;
+    reset: () => void;
+    /**
+     * Executes an async function, updates state, and returns a [err, data] tuple.
+     * Allows immediate result handling without try/catch.
+     *
+     * @example
+     * const [err, data] = await execute(() => ContactsApis.create(payload));
+     * if (err) return showAlert(err.message, 'error');
+     * showAlert('Created!', 'success');
+     */
+    execute: (asyncFn: () => Promise<T>, options?: {
+        onSuccess?: (data: T) => void;
+        onError?: (error: Error) => void;
+    }) => Promise<[Error, null] | [null, T]>;
+}
+/**
+ * Generic async state machine — tracks data, status, and error for any async operation.
+ * Pair with any async function: API calls, file reads, timers, etc.
+ *
+ * @param initialData - Optional initial data value. Default: null
+ *
+ * @example
+ * const { data, isLoading, isError, execute } = useAsyncState<User>();
+ *
+ * const handleSubmit = async () => {
+ *   const [err, user] = await execute(() => fetchUser(id));
+ *   if (err) return;
+ *   console.log(user.name);
+ * };
+ */
+declare function useAsyncState<T>(initialData?: T | null): VSUseAsyncStateReturn<T>;
+
+/**
+ * Tracks elapsed time from a given start timestamp — useful for call durations,
+ * countdowns, or any elapsed-time display.
+ *
+ * @param startedAt - Unix timestamp in ms (e.g. Date.now()). Pass null/undefined to reset.
+ * @returns Formatted duration string "MM:SS"
+ *
+ * @example
+ * const duration = useCallTimer(call.startedAt);
+ * // duration → "02:45"
+ *
+ * // Reset when no active call
+ * const duration = useCallTimer(activeCall ? activeCall.startedAt : null);
+ */
+declare function useCallTimer(startedAt?: number | null): string;
+
+interface VSModalReturn<T> {
+    isOpen: boolean;
+    data: T | null;
+    isLoading: boolean;
+    openCreateModal: () => void;
+    openEditModal: (editData: T) => void;
+    setLoading: (loading: boolean) => void;
+    closeModal: () => void;
+    setModal: (open: boolean, editData?: T | null) => void;
+}
+/**
+ * Manages modal open/close state with optional data payload and loading state.
+ * Works for both create and edit modals — pass data to distinguish the mode.
+ *
+ * @typeParam T - The type of data the modal operates on (e.g. a Contact, User, etc.)
+ *
+ * @example
+ * const modal = useModal<Contact.Base>();
+ *
+ * modal.openCreateModal();      // data → null (create mode)
+ * modal.openEditModal(contact); // data → contact (edit mode)
+ *
+ * if (modal.data) {
+ *   // Edit mode — modal.data is Contact.Base
+ * } else {
+ *   // Create mode
+ * }
+ */
+declare function useModal<T = unknown>(): VSModalReturn<T>;
+
+interface VSPaginationReturn {
+    page: number;
+    limit: number;
+    onPaginationChange: (newPage: number, newLimit: number) => void;
+    resetPagination: () => void;
+    setPage: (page: number) => void;
+    setLimit: (limit: number) => void;
+    /** Ready-to-use query params object — pass directly to useList() */
+    queryParams: VSQueryParams;
+}
+/**
+ * Manages pagination state and produces a ready-to-use queryParams object
+ * compatible with createResourceHooks' useList() and useInfinite().
+ *
+ * @param initialPage  - Starting page. Default: 1
+ * @param initialLimit - Items per page. Default: 10
+ *
+ * @example
+ * const { queryParams, onPaginationChange } = usePagination(1, 20);
+ *
+ * const { list, isLoading } = contactHooks.useList(queryParams);
+ *
+ * <Pagination onChange={onPaginationChange} total={pagination.totalDocuments} />
+ */
+declare function usePagination(initialPage?: number, initialLimit?: number): VSPaginationReturn;
+
+export { type VSAlertState, type VSAlertVariant, type VSAsyncStatus, type VSModalReturn, type VSPaginationReturn, type VSResourceHooksOptions, type VSUseAsyncStateReturn, type VSUseGetReturn, type VSUseListReturn, createResourceHooks, useAlertMessage, useAsyncState, useCallTimer, useModal, usePagination };