@reause/math 0.1.2

package/dist/index.js

@@ -0,0 +1,508 @@
+import { clamp, useControllableState } from "@reause/shared";
+import { useCallback, useMemo } from "react";
+//#region createGenericProjection/index.tsx
+/**
+* React port of VueUse's `createGenericProjection`.
+*
+* Map from @vueuse/math `createGenericProjection`
+* Mapping: `ComputedRef<T>` → a plain projector function returning a plain `T`.
+* React has no reactive graph, so the returned projector recomputes the
+* projection on every call (nothing is memoized) and the caller drives
+* re-renders. Domains and input are plain values (`MaybeRefOrGetter` is not
+* supported) — re-create the projector when a domain changes.
+*
+* @__NO_SIDE_EFFECTS__
+* @example
+* const projector = createGenericProjection(
+*   [0, 10],
+*   ['low', 'high'],
+*   (input, from, to) => (input > (from[0] + from[1]) / 2 ? to[1] : to[0]),
+* )
+* projector(8) // 'high'
+*/
+function createGenericProjection(fromDomain, toDomain, projector) {
+	return (input) => projector(input, fromDomain, toDomain);
+}
+//#endregion
+//#region createProjection/index.tsx
+function defaultNumericProjector(input, from, to) {
+	return (input - from[0]) / (from[1] - from[0]) * (to[1] - to[0]) + to[0];
+}
+/**
+* React port of VueUse's `createProjection`.
+*
+* Map from @vueuse/math `createProjection`
+* Mapping: `ComputedRef<number>` → a plain projector function returning a plain
+* `number`. React has no reactive graph, so the returned projector recomputes
+* the numeric projection on every call and the caller drives re-renders; the
+* domains are plain values (`MaybeRefOrGetter` is not supported) — re-create the
+* projector when a domain changes. Delegates to `createGenericProjection` with
+* the default numeric projector.
+*
+* @__NO_SIDE_EFFECTS__
+* @example
+* const projector = createProjection([0, 10], [0, 100])
+* projector(5) // 50
+*/
+function createProjection(fromDomain, toDomain, projector = defaultNumericProjector) {
+	return createGenericProjection(fromDomain, toDomain, projector);
+}
+//#endregion
+//#region logicAnd/index.tsx
+/**
+* `AND` condition for values — `true` only when every argument is truthy.
+*
+* Map from @vueuse/math `logicAnd`
+* (`source/vueuse/packages/math/logicAnd/`). Upstream wraps the evaluation in
+* `computed(() => ...)` and returns a `ComputedRef<boolean>`; the reause
+* version is a pure function that evaluates every plain argument and returns a
+* plain `boolean` on each call — there is no reactivity, so re-renders (or
+* effects) drive re-evaluation (SSR-safe).
+*
+* React divergence: arguments are plain values, not upstream's
+* `MaybeRefOrGetter<any>[]`.
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* logicAnd(true, 1, 'foo') // true
+* logicAnd(true, false) // false
+*
+* @param args - Values to test.
+* @returns `true` when every argument is truthy, `false` otherwise.
+*/
+function logicAnd(...args) {
+	return args.every((value) => value);
+}
+//#endregion
+//#region logicNot/index.tsx
+/**
+* `NOT` condition for values — the logical complement of the given value.
+*
+* Map from @vueuse/math `logicNot`
+* (`source/vueuse/packages/math/logicNot/`). Upstream wraps the evaluation in
+* `computed(() => ...)` and returns a `ComputedRef<boolean>`; the reause
+* version is a pure function that evaluates the plain argument and returns a
+* plain `boolean` on each call — there is no reactivity, so re-renders (or
+* effects) drive re-evaluation (SSR-safe).
+*
+* React divergence: the argument is a plain value, not upstream's
+* `MaybeRefOrGetter<any>`.
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* logicNot(true) // false
+* logicNot(0) // true
+* logicNot('foo') // false
+*
+* @param v - A value to negate.
+* @returns `true` when the value is falsy, `false` otherwise.
+*/
+function logicNot(v) {
+	return !v;
+}
+//#endregion
+//#region logicOr/index.tsx
+/**
+* `OR` conditions for values.
+*
+* Map from @vueuse/math `logicOr`
+* (`source/vueuse/packages/math/logicOr/`). Compute the logical `OR` of any
+* number of values.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<boolean>`; the reause version is a pure utility
+* function — all plain arguments are evaluated on every call and the plain
+* boolean result is returned directly, with no effects and no `.value` wrapper
+* (SSR-safe). The caller re-invokes it to react to changing values.
+*
+* React divergence: arguments are plain values, not upstream's
+* `MaybeRefOrGetter<any>[]`.
+*
+* @see https://vueuse.org/math/logicOr/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* logicOr(true, false) // true
+* logicOr(false, 0, '') // false
+*
+* @param args - Values to evaluate.
+* @returns `true` if any argument is truthy, `false` otherwise.
+*/
+function logicOr(...args) {
+	return args.some((i) => i);
+}
+//#endregion
+//#region useAbs/index.tsx
+/**
+* React port of VueUse's `useAbs`.
+*
+* Map from @vueuse/math `useAbs`
+* (`source/vueuse/packages/math/useAbs/`). Reactive `Math.abs`.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `number` argument is read at render time and `Math.abs` is
+* applied directly, with no effects and no `.value` wrapper (SSR-safe).
+*
+* React divergence: `value` is a plain read-only `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with a new value (e.g. from
+* `useState`) and the hook recomputes.
+*
+* @see https://vueuse.org/math/useAbs/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useAbs(-23) // 23
+*
+* @param value - The number to compute the absolute value of.
+* @returns The absolute value of the value.
+*/
+function useAbs(value) {
+	return Math.abs(value);
+}
+//#endregion
+//#region utils/index.tsx
+/**
+* Flatten the composable arguments into a plain number array.
+* Mirrors VueUse math's `toValueArgsFlat` (`source/vueuse/packages/math/utils.ts`),
+* narrowed to plain values because the arguments are read-only value sources.
+*
+* Shared by the variadic math hooks (`useAverage`, `useSum`, `useMax`,
+* `useMin`) — upstream centralizes this in the math package's `utils.ts`, so
+* the reause port keeps a single copy here instead of four.
+*
+* @__NO_SIDE_EFFECTS__
+*/
+function toArgsFlat(args) {
+	return args.flatMap((item) => Array.isArray(item) ? [...item] : [item]);
+}
+//#endregion
+//#region useAverage/index.tsx
+function useAverage(...args) {
+	const values = toArgsFlat(args);
+	return values.length === 0 ? 0 : values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+//#endregion
+//#region useCeil/index.tsx
+/**
+* React port of VueUse's `useCeil`.
+*
+* Map from @vueuse/math `useCeil`
+* (`source/vueuse/packages/math/useCeil/`). Reactive `Math.ceil`.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `number` argument is read at render time and `Math.ceil` is
+* applied directly, with no effects and no `.value` wrapper (SSR-safe).
+*
+* React divergence: `value` is a plain read-only `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with a new value (e.g. from
+* `useState`) and the hook recomputes.
+*
+* @see https://vueuse.org/math/useCeil/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useCeil(0.95) // 1
+*
+* @param value - The number to ceil.
+* @returns The ceil of the value.
+*/
+function useCeil(value) {
+	return Math.ceil(value);
+}
+//#endregion
+//#region useClamp/index.tsx
+/**
+* Reactively clamp a value between two other values.
+*
+* Map from @vueuse/math `useClamp`
+* (`source/vueuse/packages/math/useClamp/`). React port of VueUse's writable
+* `useClamp` — returns a `[value, setValue]` tuple whose setter clamps on
+* write. `value`, `min` and `max` are plain read-only numbers resolved on every
+* render: `value` seeds the hook's internal state (and re-syncs when it
+* changes), and bounds are re-resolved on every render and on every set, so
+* shrinking `max` / raising `min` re-clamps the current value automatically.
+*
+* React divergence: all three parameters are plain `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with new values (e.g. from
+* `useState`) instead of passing a ref/getter. Upstream's writable computed
+* also writes the clamped value back into its internal ref on every read, so an
+* out-of-bounds seed stays clamped even after the bounds loosen; here `value`
+* is a plain prop that re-seeds internal state when it changes and the raw seed
+* is re-clamped on every render, so loosening the bounds re-exposes the raw
+* seed until the next `setValue`.
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const [value, setValue] = useClamp(0, 0, 10)
+* setValue(15) // value is 10
+* setValue(-5) // value is 0
+*
+* @param value - The value to clamp.
+* @param min - The lower bound.
+* @param max - The upper bound.
+* @returns A `[value, setValue]` pair; `setValue` clamps into `[min, max]`.
+*/
+function useClamp(value, min, max) {
+	const [raw, setRaw] = useControllableState(value, { passive: true });
+	return [clamp(raw, min, max), useCallback((next) => {
+		setRaw(clamp(next, min, max));
+	}, [
+		setRaw,
+		min,
+		max
+	])];
+}
+//#endregion
+//#region useFloor/index.tsx
+/**
+* React port of VueUse's `useFloor`.
+*
+* Map from @vueuse/math `useFloor`
+* (`source/vueuse/packages/math/useFloor/`). Reactive `Math.floor`.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `number` argument is read at render time and `Math.floor` is
+* applied directly, with no effects and no `.value` wrapper (SSR-safe).
+*
+* React divergence: `value` is a plain read-only `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with a new value (e.g. from
+* `useState`) and the hook recomputes.
+*
+* @see https://vueuse.org/math/useFloor/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useFloor(45.95) // 45
+*
+* @param value - The number to floor.
+* @returns The floor of the value.
+*/
+function useFloor(value) {
+	return Math.floor(value);
+}
+//#endregion
+//#region useMath/index.tsx
+/**
+* React port of VueUse's `useMath`.
+*
+* Map from @vueuse/math `useMath`
+* (`source/vueuse/packages/math/useMath/`). Reactive `Math` methods — pass a
+* `Math` method name as the key and its plain numeric arguments; the result is
+* recomputed on every render and returned directly, with no `.value` wrapper
+* and no effects (SSR-safe).
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* via `reactify` and returns a `ComputedRef<number>`; the reause version is a
+* pure derived hook — `key` and every argument are read at render time and
+* `Math[key]` is invoked immediately, so the returned number always reflects
+* the latest values.
+*
+* React divergence: arguments are plain numbers, not upstream's
+* `MaybeRefOrGetter`. In particular the getter form (`() => number`) is NOT
+* accepted — getters as data sources are rejected repo-wide (issue #462). The
+* caller re-renders with new values (e.g. from `useState`).
+*
+* @see https://vueuse.org/math/useMath/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useMath('pow', 2, 3) // 8
+*
+* const power = useMath('pow', 2, 3) // 8
+*
+* const root = useMath('sqrt', 4) // 2
+*
+* const rounded = useMath('round', 2.5) // 3
+*
+* @param key - The `Math` method name to call (e.g. `'pow'`, `'sqrt'`).
+* @param args - Plain numeric arguments to pass to the `Math` method.
+* @returns The result of calling `Math[key]` with the arguments.
+*/
+function useMath(key, ...args) {
+	const fn = Math[key];
+	return fn(...args);
+}
+//#endregion
+//#region useMax/index.tsx
+function useMax(...args) {
+	return Math.max(...toArgsFlat(args));
+}
+//#endregion
+//#region useMin/index.tsx
+function useMin(...args) {
+	return Math.min(...toArgsFlat(args));
+}
+//#endregion
+//#region usePrecision/index.tsx
+/**
+* Accuracy of handling numerical values.
+*
+* @param value - The value
+* @param power - The power
+* @returns The result of multiplying the value with the power
+*/
+function accurateMultiply(value, power) {
+	const valueStr = value.toString();
+	if (value > 0 && valueStr.includes(".")) {
+		const multiplier = 10 ** valueStr.split(".")[1].length;
+		return value * multiplier * power / multiplier;
+	} else return value * power;
+}
+/**
+* React port of VueUse's `usePrecision`.
+*
+* Map from @vueuse/math `usePrecision`
+* (`source/vueuse/packages/math/usePrecision/`). Reactively set the precision
+* of a number.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `value`, `digits` and `options` are read at render time and
+* the precision-adjusted number is memoized and returned directly, with no
+* effects and no `.value` wrapper (SSR-safe).
+*
+* React divergence: parameters are plain read-only values, not upstream's
+* `MaybeRefOrGetter<...>`. The caller re-renders with new values (e.g. from
+* `useState`).
+*
+* @see https://vueuse.org/math/usePrecision/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = usePrecision(3.1415, 2) // 3.14
+*
+* const ceilResult = usePrecision(3.1415, 2, {
+*   math: 'ceil',
+* }) // 3.15
+*
+* const floorResult = usePrecision(3.1415, 3, {
+*   math: 'floor',
+* }) // 3.141
+*
+* @param value - The value to set the precision of.
+* @param digits - The number of digits to keep.
+* @param options - The rounding method to use (`round` by default).
+* @returns The value with the applied precision.
+*/
+function usePrecision(value, digits, options) {
+	return useMemo(() => {
+		const power = 10 ** digits;
+		return Math[(options === null || options === void 0 ? void 0 : options.math) || "round"](accurateMultiply(value, power)) / power;
+	}, [
+		value,
+		digits,
+		options
+	]);
+}
+//#endregion
+//#region useProjection/index.tsx
+/**
+* React port of VueUse's `useProjection`.
+*
+* Map from @vueuse/math `useProjection`
+* Mapping: `ComputedRef<number>` → plain number recomputed from the current
+* value on every render; pure derived value — no reactive `.value`, the caller
+* drives re-renders.
+*
+* React divergence: `input`, `fromDomain` and `toDomain` are all plain
+* read-only values, not upstream's `MaybeRefOrGetter<...>`. In particular the
+* getter form (`() => number`) is NOT accepted — getters as data sources are
+* rejected repo-wide (issue #462). The caller re-renders with new values (e.g.
+* from `useState`) and the hook recomputes. Like upstream, the projection is
+* delegated to `createProjection` (its default projector is the linear numeric
+* projector), so the projector function is not duplicated here.
+*
+* @param input - The input value to project.
+* @param fromDomain - The source domain (a plain `readonly [number, number]`).
+* @param toDomain - The target domain (a plain `readonly [number, number]`).
+* @param projector - The projector function (defaults to the linear numeric projector).
+* @returns The projected number.
+*
+* @__NO_SIDE_EFFECTS__
+* @example
+* const projected = useProjection(5, [0, 10], [0, 100]) // 50
+*/
+function useProjection(input, fromDomain, toDomain, projector) {
+	return createProjection(fromDomain, toDomain, projector)(input);
+}
+//#endregion
+//#region useRound/index.tsx
+/**
+* React port of VueUse's `useRound`.
+*
+* Map from @vueuse/math `useRound`
+* (`source/vueuse/packages/math/useRound/`). Reactive `Math.round`.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `number` argument is read at render time and `Math.round` is
+* applied directly, with no effects and no `.value` wrapper (SSR-safe).
+*
+* React divergence: `value` is a plain read-only `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with a new value (e.g. from
+* `useState`) and the hook recomputes.
+*
+* @see https://vueuse.org/math/useRound/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useRound(20.49) // 20
+*
+* @param value - The number to round.
+* @returns The value rounded to the nearest integer.
+*/
+function useRound(value) {
+	return Math.round(value);
+}
+//#endregion
+//#region useSum/index.tsx
+function useSum(...args) {
+	return toArgsFlat(args).reduce((sum, v) => sum + v, 0);
+}
+//#endregion
+//#region useTrunc/index.tsx
+/**
+* React port of VueUse's `useTrunc`.
+*
+* Map from @vueuse/math `useTrunc`
+* (`source/vueuse/packages/math/useTrunc/`). Reactively truncates a number,
+* removing the fractional digits toward zero.
+*
+* Adjustment for React: upstream wraps the computation in `computed(() => ...)`
+* and returns a `ComputedRef<number>`; the reause version is a pure derived
+* hook — the plain `number` argument is read at render time and the truncated
+* number is returned directly, with no effects and no `.value` wrapper
+* (SSR-safe).
+*
+* React divergence: `value` is a plain read-only `number`, not upstream's
+* `MaybeRefOrGetter<number>`. The caller re-renders with a new value (e.g. from
+* `useState`) and the hook recomputes.
+*
+* @see https://vueuse.org/math/useTrunc/
+*
+* @__NO_SIDE_EFFECTS__
+*
+* @example
+* const result = useTrunc(0.95) // 0
+*
+* @param value - The number to truncate.
+* @returns The truncated number.
+*/
+function useTrunc(value) {
+	return Math.trunc(value);
+}
+//#endregion
+export { createGenericProjection, createProjection, logicAnd, logicNot, logicOr, useAbs, useAverage, useCeil, useClamp, useFloor, useMath, useMax, useMin, usePrecision, useProjection, useRound, useSum, useTrunc };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@reause/math",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "Math functions — React port of @vueuse/math (experimental, AI-mapped)",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "unpkg": "./dist/index.iife.min.js",
+  "jsdelivr": "./dist/index.iife.min.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@reause/shared": "0.1.2"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}