@kopexa/react-utils 1.1.0 → 2.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @kopexa/react-utils
+
+A powerful utility toolkit for advanced React development, part of the Kopexa Sight Design System.
+
+---
+
+## Overview
+
+`@kopexa/react-utils` provides essential utilities for building robust, scalable, and maintainable React applications. It includes advanced context creation and ref management utilities, designed for modern React (v19+) and seamless integration with the Kopexa Sight ecosystem.
+
+- **Author:** Kopexa (<https://kopexa.com>)
+- **License:** MIT
+- **Repository:** [kopexa-grc/sight](https://github.com/kopexa-grc/sight)
+
+## Features
+
+- **createContext**: Type-safe, ergonomic context creation with strict mode and custom error messages.
+- **mergeRefs**: Effortlessly merge multiple refs (callback and object) for advanced component composition.
+- **TypeScript-first**: Fully typed APIs for maximum safety and DX.
+- **Zero dependencies**: Only peer-depends on React.
+
+## Installation
+
+```sh
+pnpm add @kopexa/react-utils
+# or
+yarn add @kopexa/react-utils
+# or
+npm install @kopexa/react-utils
+```
+
+## API
+
+### `createContext<T>(options?: CreateContextOptions<T>): [Provider, useContext, Context]`
+
+A strict, ergonomic alternative to React's context API.
+
+```tsx
+import { createContext } from '@kopexa/react-utils';
+
+const [Provider, useMyContext] = createContext<number>({
+  name: 'MyContext',
+  strict: true,
+  hookName: 'useMyContext',
+  providerName: 'MyProvider',
+});
+
+function MyComponent() {
+  const value = useMyContext();
+  // ...
+}
+```
+
+#### Options
+- `strict` (default: true): Throws if context is missing.
+- `hookName`, `providerName`, `errorMessage`, `name`, `defaultValue`: Customize error and context behavior.
+
+### `mergeRefs<T>(...refs: Ref<T>[]): Ref<T>`
+
+Merge multiple refs (callback or object) into a single ref for advanced component composition.
+
+```tsx
+import { mergeRefs } from '@kopexa/react-utils';
+
+function MyInput(props, ref) {
+  return <input ref={mergeRefs(ref, props.innerRef)} />;
+}
+```
+
+## Best Practices
+
+- Use `createContext` for all new context providers in your app or library for safer, more maintainable code.
+- Use `mergeRefs` when you need to forward refs to multiple consumers (e.g., HOCs, hooks, portals).
+
+## Why Kopexa Sight?
+
+Kopexa Sight is dedicated to building reliable, developer-friendly open source tools. This package is designed for clarity, stability, and best practices, inspired by the Google API Design Guide.
+
+## License
+
+MIT © Kopexa

package/dist/chunk-2DAVPPDT.mjs

@@ -0,0 +1,40 @@
+"use client";
+
+// src/context.ts
+import {
+  createContext as createReactContext,
+  useContext as useReactContext
+} from "react";
+function getErrorMessage(hook, provider) {
+  return `${hook} returned \`undefined\`. Seems you forgot to wrap component within ${provider}`;
+}
+function createContext(options = {}) {
+  const {
+    name,
+    strict = true,
+    hookName = "useContext",
+    providerName = "Provider",
+    errorMessage,
+    defaultValue
+  } = options;
+  const Context = createReactContext(defaultValue);
+  Context.displayName = name;
+  function useContext() {
+    var _a;
+    const context = useReactContext(Context);
+    if (!context && strict) {
+      const error = new Error(
+        errorMessage != null ? errorMessage : getErrorMessage(hookName, providerName)
+      );
+      error.name = "ContextError";
+      (_a = Error.captureStackTrace) == null ? void 0 : _a.call(Error, error, useContext);
+      throw error;
+    }
+    return context;
+  }
+  return [Context.Provider, useContext, Context];
+}
+
+export {
+  createContext
+};

package/dist/chunk-FGSQ5KEN.mjs

@@ -0,0 +1,23 @@
+"use client";
+
+// src/dom.ts
+function mergeRefs(...inputRefs) {
+  const filteredInputRefs = inputRefs.filter(Boolean);
+  if (filteredInputRefs.length <= 1) {
+    const firstRef = filteredInputRefs[0];
+    return firstRef || null;
+  }
+  return function mergedRefs(ref) {
+    for (const inputRef of filteredInputRefs) {
+      if (typeof inputRef === "function") {
+        inputRef(ref);
+      } else if (inputRef) {
+        inputRef.current = ref;
+      }
+    }
+  };
+}
+
+export {
+  mergeRefs
+};

package/dist/context.d.mts

@@ -0,0 +1,16 @@
+interface CreateContextOptions<T> {
+    strict?: boolean;
+    hookName?: string;
+    providerName?: string;
+    errorMessage?: string;
+    name?: string;
+    defaultValue?: T;
+}
+type CreateContextReturn<T> = [
+    React.Provider<T>,
+    () => T,
+    React.Context<T>
+];
+declare function createContext<T>(options?: CreateContextOptions<T>): CreateContextReturn<T>;
+
+export { type CreateContextOptions, type CreateContextReturn, createContext };

package/dist/context.js

@@ -1,3 +1,4 @@
+"use client";
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -39,13 +40,14 @@ function createContext(options = {}) {
   const Context = (0, import_react.createContext)(defaultValue);
   Context.displayName = name;
   function useContext() {
+    var _a;
     const context = (0, import_react.useContext)(Context);
     if (!context && strict) {
       const error = new Error(
-        errorMessage ?? getErrorMessage(hookName, providerName)
+        errorMessage != null ? errorMessage : getErrorMessage(hookName, providerName)
       );
       error.name = "ContextError";
-      Error.captureStackTrace?.(error, useContext);
+      (_a = Error.captureStackTrace) == null ? void 0 : _a.call(Error, error, useContext);
       throw error;
     }
     return context;

package/dist/context.mjs

@@ -0,0 +1,7 @@
+"use client";
+import {
+  createContext
+} from "./chunk-2DAVPPDT.mjs";
+export {
+  createContext
+};

package/dist/dom.d.mts

@@ -0,0 +1,17 @@
+import { Ref, RefCallback } from 'react';
+
+/**
+ * A function that merges React refs into one.
+ * Supports both functions and ref objects created using createRef() and useRef().
+ *
+ * Usage:
+ * ```tsx
+ * <div ref={mergeRefs(ref1, ref2, ref3)} />
+ * ```
+ *
+ * @param {(Ref<T> | undefined)[]} inputRefs Array of refs
+ * @returns {Ref<T> | RefCallback<T>} Merged refs
+ */
+declare function mergeRefs<T>(...inputRefs: (Ref<T> | undefined)[]): Ref<T> | RefCallback<T>;
+
+export { mergeRefs };

package/dist/dom.js

@@ -1,3 +1,4 @@
+"use client";
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/dom.mjs

@@ -0,0 +1,7 @@
+"use client";
+import {
+  mergeRefs
+} from "./chunk-FGSQ5KEN.mjs";
+export {
+  mergeRefs
+};

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export { createContext } from './context.mjs';
+export { mergeRefs } from './dom.mjs';
+import 'react';

package/dist/index.js

@@ -1,3 +1,4 @@
+"use client";
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -42,13 +43,14 @@ function createContext(options = {}) {
   const Context = (0, import_react.createContext)(defaultValue);
   Context.displayName = name;
   function useContext() {
+    var _a;
     const context = (0, import_react.useContext)(Context);
     if (!context && strict) {
       const error = new Error(
-        errorMessage ?? getErrorMessage(hookName, providerName)
+        errorMessage != null ? errorMessage : getErrorMessage(hookName, providerName)
       );
       error.name = "ContextError";
-      Error.captureStackTrace?.(error, useContext);
+      (_a = Error.captureStackTrace) == null ? void 0 : _a.call(Error, error, useContext);
       throw error;
     }
     return context;

package/dist/index.mjs

@@ -0,0 +1,11 @@
+"use client";
+import {
+  createContext
+} from "./chunk-2DAVPPDT.mjs";
+import {
+  mergeRefs
+} from "./chunk-FGSQ5KEN.mjs";
+export {
+  createContext,
+  mergeRefs
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kopexa/react-utils",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A set of utilities for react on client side",
   "keywords": [
     "react-utils"