@kopexa/use-controllable-state 0.0.0-canary-20250718183330

package/README.md

@@ -0,0 +1,72 @@
+# @kopexa/use-controllable-state
+
+A React hook for building controlled and uncontrolled components, designed for clarity and reliability in the style of the Google API Design Guide.
+
+---
+
+## Overview
+
+`@kopexa/use-controllable-state` provides a robust pattern for managing state in React components that can be either controlled (via props) or uncontrolled (internal state). This hook is ideal for reusable UI components and libraries.
+
+- **Author:** Kopexa (<https://kopexa.com>)
+- **License:** MIT
+- **Repository:** [kopexa-grc/sight](https://github.com/kopexa-grc/sight)
+
+## Features
+
+- Supports both controlled and uncontrolled usage
+- Customizable change detection with `shouldUpdate`
+- TypeScript support
+- Lightweight and dependency-free (except React)
+
+## Installation
+
+```sh
+pnpm add @kopexa/use-controllable-state
+# or
+yarn add @kopexa/use-controllable-state
+# or
+npm install @kopexa/use-controllable-state
+```
+
+## Usage
+
+```tsx
+import { useControllableState } from '@kopexa/use-controllable-state';
+
+function MyComponent(props) {
+  const [value, setValue] = useControllableState({
+    value: props.value,
+    defaultValue: 0,
+    onChange: props.onChange,
+  });
+
+  return <input value={value} onChange={e => setValue(e.target.value)} />;
+}
+```
+
+## API
+
+### `useControllableState<T>(props: UseControllableStateProps<T>): [T, Dispatch<SetStateAction<T>>]`
+
+- **props**: See below for details.
+- **Returns**: `[value, setValue]` — the current value and a setter function.
+
+#### `UseControllableStateProps<T>`
+- `value?`: Controlled value
+- `defaultValue?`: Initial value for uncontrolled usage
+- `onChange?`: Callback when value changes
+- `shouldUpdate?`: Custom comparison function
+
+## Best Practices
+
+- Use for components that can be both controlled and uncontrolled.
+- Provide clear documentation for consumers of your component.
+
+## Why Kopexa?
+
+Kopexa (<https://kopexa.com>) builds 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/index.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Determines if a component is controlled (receives its value from props) or uncontrolled (manages its own state).
+ * Returns a tuple: [isControlled, value].
+ *
+ * @template T - The type of the value.
+ * @param prop - The controlled value from props, or undefined if uncontrolled.
+ * @param state - The internal state value.
+ * @returns [boolean, T] - Whether the component is controlled, and the current value.
+ */
+declare function useControllableProp<T>(prop: T | undefined, state: T): [boolean, T];
+/**
+ * Props for the useControllableState hook.
+ *
+ * @template T - The type of the value.
+ * @property value - The controlled value (if provided).
+ * @property defaultValue - The initial value for uncontrolled usage.
+ * @property onChange - Callback fired when the value changes.
+ * @property shouldUpdate - Custom comparison function to determine if the value should update.
+ */
+interface UseControllableStateProps<T> {
+    value?: T;
+    defaultValue?: T | (() => T);
+    onChange?: (value: T) => void;
+    shouldUpdate?: (prev: T, next: T) => boolean;
+}
+/**
+ * A React hook for building controlled or uncontrolled components.
+ *
+ * - If `value` is provided, the component is controlled and must be updated via `onChange`.
+ * - If `value` is not provided, the component manages its own state internally.
+ *
+ * Returns a tuple: [value, setValue].
+ *
+ * @template T - The type of the value.
+ * @param props - The props for controlling the state.
+ * @returns [T, Dispatch<SetStateAction<T>>] - The current value and a setter function.
+ *
+ * @example
+ * const [value, setValue] = useControllableState({
+ *   value: props.value,
+ *   defaultValue: 0,
+ *   onChange: props.onChange,
+ * });
+ */
+declare function useControllableState<T>(props: UseControllableStateProps<T>): [T, React.Dispatch<React.SetStateAction<T>>];
+
+export { type UseControllableStateProps, useControllableProp, useControllableState };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Determines if a component is controlled (receives its value from props) or uncontrolled (manages its own state).
+ * Returns a tuple: [isControlled, value].
+ *
+ * @template T - The type of the value.
+ * @param prop - The controlled value from props, or undefined if uncontrolled.
+ * @param state - The internal state value.
+ * @returns [boolean, T] - Whether the component is controlled, and the current value.
+ */
+declare function useControllableProp<T>(prop: T | undefined, state: T): [boolean, T];
+/**
+ * Props for the useControllableState hook.
+ *
+ * @template T - The type of the value.
+ * @property value - The controlled value (if provided).
+ * @property defaultValue - The initial value for uncontrolled usage.
+ * @property onChange - Callback fired when the value changes.
+ * @property shouldUpdate - Custom comparison function to determine if the value should update.
+ */
+interface UseControllableStateProps<T> {
+    value?: T;
+    defaultValue?: T | (() => T);
+    onChange?: (value: T) => void;
+    shouldUpdate?: (prev: T, next: T) => boolean;
+}
+/**
+ * A React hook for building controlled or uncontrolled components.
+ *
+ * - If `value` is provided, the component is controlled and must be updated via `onChange`.
+ * - If `value` is not provided, the component manages its own state internally.
+ *
+ * Returns a tuple: [value, setValue].
+ *
+ * @template T - The type of the value.
+ * @param props - The props for controlling the state.
+ * @returns [T, Dispatch<SetStateAction<T>>] - The current value and a setter function.
+ *
+ * @example
+ * const [value, setValue] = useControllableState({
+ *   value: props.value,
+ *   defaultValue: 0,
+ *   onChange: props.onChange,
+ * });
+ */
+declare function useControllableState<T>(props: UseControllableStateProps<T>): [T, React.Dispatch<React.SetStateAction<T>>];
+
+export { type UseControllableStateProps, useControllableProp, useControllableState };

package/dist/index.js

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useControllableProp: () => useControllableProp,
+  useControllableState: () => useControllableState
+});
+module.exports = __toCommonJS(index_exports);
+var import_use_callback_ref = require("@kopexa/use-callback-ref");
+var import_react = require("react");
+function useControllableProp(prop, state) {
+  const controlled = typeof prop !== "undefined";
+  const value = controlled ? prop : state;
+  return (0, import_react.useMemo)(() => [controlled, value], [controlled, value]);
+}
+function useControllableState(props) {
+  const {
+    value: valueProp,
+    defaultValue,
+    onChange,
+    shouldUpdate = (prev, next) => prev !== next
+  } = props;
+  const onChangeProp = (0, import_use_callback_ref.useCallbackRef)(onChange);
+  const shouldUpdateProp = (0, import_use_callback_ref.useCallbackRef)(shouldUpdate);
+  const [uncontrolledState, setUncontrolledState] = (0, import_react.useState)(defaultValue);
+  const controlled = valueProp !== void 0;
+  const value = controlled ? valueProp : uncontrolledState;
+  const setValue = (0, import_use_callback_ref.useCallbackRef)(
+    (next) => {
+      const setter = next;
+      const nextValue = typeof next === "function" ? setter(value) : next;
+      if (!shouldUpdateProp(value, nextValue)) {
+        return;
+      }
+      if (!controlled) {
+        setUncontrolledState(nextValue);
+      }
+      onChangeProp(nextValue);
+    },
+    [controlled, onChangeProp, value, shouldUpdateProp]
+  );
+  return [value, setValue];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useControllableProp,
+  useControllableState
+});

package/dist/index.mjs

@@ -0,0 +1,40 @@
+// src/index.ts
+import { useCallbackRef } from "@kopexa/use-callback-ref";
+import { useMemo, useState } from "react";
+function useControllableProp(prop, state) {
+  const controlled = typeof prop !== "undefined";
+  const value = controlled ? prop : state;
+  return useMemo(() => [controlled, value], [controlled, value]);
+}
+function useControllableState(props) {
+  const {
+    value: valueProp,
+    defaultValue,
+    onChange,
+    shouldUpdate = (prev, next) => prev !== next
+  } = props;
+  const onChangeProp = useCallbackRef(onChange);
+  const shouldUpdateProp = useCallbackRef(shouldUpdate);
+  const [uncontrolledState, setUncontrolledState] = useState(defaultValue);
+  const controlled = valueProp !== void 0;
+  const value = controlled ? valueProp : uncontrolledState;
+  const setValue = useCallbackRef(
+    (next) => {
+      const setter = next;
+      const nextValue = typeof next === "function" ? setter(value) : next;
+      if (!shouldUpdateProp(value, nextValue)) {
+        return;
+      }
+      if (!controlled) {
+        setUncontrolledState(nextValue);
+      }
+      onChangeProp(nextValue);
+    },
+    [controlled, onChangeProp, value, shouldUpdateProp]
+  );
+  return [value, setValue];
+}
+export {
+  useControllableProp,
+  useControllableState
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@kopexa/use-controllable-state",
+  "version": "0.0.0-canary-20250718183330",
+  "description": "A hook to provide a controllable state",
+  "keywords": [
+    "use-controllable-state"
+  ],
+  "author": "Kopexa <hello@kopexa.com>",
+  "homepage": "https://kopexa.com",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kopexa-grc/sight.git",
+    "directory": "packages/hooks/use-controllable-state"
+  },
+  "bugs": {
+    "url": "https://github.com/kopexa-grc/sight/issues"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0-rc.0"
+  },
+  "dependencies": {
+    "@kopexa/use-callback-ref": "0.0.0-canary-20250718183330"
+  },
+  "clean-package": "../../../clean-package.config.json",
+  "tsup": {
+    "clean": true,
+    "target": "es2019",
+    "format": [
+      "cjs",
+      "esm"
+    ]
+  },
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup src --dts",
+    "build:fast": "tsup src",
+    "dev": "pnpm build:fast --watch",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc --noEmit"
+  }
+}