@restart/hooks - npm Package Compare versions

Comparing version 0.2.7 to 0.2.8

es/index.d.ts

@@ -0,1 +1,2 @@
+import useCallbackRef from './useCallbackRef';
 import useCommittedRef from './useCommittedRef';
@@ -12,2 +13,3 @@ import useEventCallback from './useEventCallback';
 import useImage from './useImage';
-export { useCommittedRef, useEventCallback, useEventListener, useGlobalListener, useInterval, useRafInterval, useMergeState, useMergeStateFromProps, useMounted, usePrevious, useImage, };
+import useResizeObserver from './useResizeObserver';
+export { useCallbackRef, useCommittedRef, useEventCallback, useEventListener, useGlobalListener, useInterval, useRafInterval, useMergeState, useMergeStateFromProps, useMounted, usePrevious, useImage, useResizeObserver, };

es/index.js

@@ -5,2 +5,6 @@ "use strict";
 
+var _useCallbackRef = _interopRequireDefault(require("./useCallbackRef"));
+
+exports.useCallbackRef = _useCallbackRef.default;
+
 var _useCommittedRef = _interopRequireDefault(require("./useCommittedRef"));
@@ -50,2 +54,6 @@
 
+var _useResizeObserver = _interopRequireDefault(require("./useResizeObserver"));
+
+exports.useResizeObserver = _useResizeObserver.default;
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

es/useCommittedRef.d.ts

 /// <reference types="react" />
+/**
+ * Creates a `Ref` whose value is updated in an effect, ensuring the most recent
+ * value is the one rendered with. Generally only required for Concurrent mode usage
+ * where previous work in `render()` may be discarded befor being used.
+ *
+ * This is safe to access in an event handler.
+ *
+ * @param value The `Ref` value
+ */
 declare function useCommittedRef<TValue>(value: TValue): React.MutableRefObject<TValue>;
 export default useCommittedRef;

es/useCommittedRef.js

@@ -8,2 +8,11 @@ "use strict";
 
+/**
+ * Creates a `Ref` whose value is updated in an effect, ensuring the most recent
+ * value is the one rendered with. Generally only required for Concurrent mode usage
+ * where previous work in `render()` may be discarded befor being used.
+ *
+ * This is safe to access in an event handler.
+ *
+ * @param value The `Ref` value
+ */
 function useCommittedRef(value) {
@@ -10,0 +19,0 @@ var ref = (0, _react.useRef)(value);

es/useEventListener.d.ts

 declare type EventHandler<T, K extends keyof DocumentEventMap> = (this: T, ev: DocumentEventMap[K]) => any;
+/**
+ * Attaches an event handler outside directly to specified DOM element
+ * bypassing the react synthetic event system.
+ *
+ * @param element The target to listen for events on
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
 export default function useEventListener<T extends Element | Document | Window, K extends keyof DocumentEventMap>(element: T, event: K, listener: EventHandler<T, K>, capture?: boolean): void;
 export {};

es/useEventListener.js

@@ -12,2 +12,11 @@ "use strict";
 
+/**
+ * Attaches an event handler outside directly to specified DOM element
+ * bypassing the react synthetic event system.
+ *
+ * @param element The target to listen for events on
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
 function useEventListener(element, event, listener, capture) {
@@ -14,0 +23,0 @@ if (capture === void 0) {

es/useGlobalListener.d.ts

 declare type DocumentEventHandler<K extends keyof DocumentEventMap> = (this: Document, ev: DocumentEventMap[K]) => any;
-export default function useGlobalListener<K extends keyof DocumentEventMap>(event: K, listener: DocumentEventHandler<K>, capture?: boolean): void;
+/**
+ * Attaches an event handler outside directly to the `document`,
+ * bypassing the react synthetic event system.
+ *
+ * ```ts
+ * useGlobalListener('keydown', (event) => {
+ *  console.log(event.key)
+ * })
+ * ```
+ *
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
+export default function useGlobalListener<K extends keyof DocumentEventMap>(event: K, handler: DocumentEventHandler<K>, capture?: boolean): void;
 export {};

es/useGlobalListener.js

@@ -10,3 +10,17 @@ "use strict";
 
-function useGlobalListener(event, listener, capture) {
+/**
+ * Attaches an event handler outside directly to the `document`,
+ * bypassing the react synthetic event system.
+ *
+ * ```ts
+ * useGlobalListener('keydown', (event) => {
+ *  console.log(event.key)
+ * })
+ * ```
+ *
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
+function useGlobalListener(event, handler, capture) {
   if (capture === void 0) {
@@ -16,3 +30,3 @@ capture = false;
 
-  return (0, _useEventListener.default)(document, event, listener, capture);
+  return (0, _useEventListener.default)(document, event, handler, capture);
 }

es/useImage.d.ts

@@ -5,3 +5,28 @@ declare type State = {
 };
-export default function useImage(imageOrUrl?: string | HTMLImageElement | null | undefined, crossOrigin?: string): State;
+/**
+ * Fetch and load an image for programatic use such as in a `<canvas>` element.
+ *
+ * @param imageOrUrl The `HtmlImageElement` or image url to load
+ * @param crossOrigin The `crossorigin` attribute to set
+ *
+ * ```ts
+ * const { image, error } = useImage('/static/kittens.png')
+ * const ref = useRef<HTMLCanvasElement>()
+ *
+ * useEffect(() => {
+ *   const ctx = ref.current.getContext('2d')
+ *
+ *   if (image) {
+ *     ctx.drawImage(image, 0, 0)
+ *   }
+ * }, [ref, image])
+ *
+ * return (
+ *   <>
+ *     {error && "there was a problem loading the image"}
+ *     <canvas ref={ref} />
+ *   </>
+ * ```
+ */
+export default function useImage(imageOrUrl?: string | HTMLImageElement | null | undefined, crossOrigin?: 'anonymous' | 'use-credentials' | string): State;
 export {};

es/useImage.js

@@ -8,2 +8,27 @@ "use strict";
 
+/**
+ * Fetch and load an image for programatic use such as in a `<canvas>` element.
+ *
+ * @param imageOrUrl The `HtmlImageElement` or image url to load
+ * @param crossOrigin The `crossorigin` attribute to set
+ *
+ * ```ts
+ * const { image, error } = useImage('/static/kittens.png')
+ * const ref = useRef<HTMLCanvasElement>()
+ *
+ * useEffect(() => {
+ *   const ctx = ref.current.getContext('2d')
+ *
+ *   if (image) {
+ *     ctx.drawImage(image, 0, 0)
+ *   }
+ * }, [ref, image])
+ *
+ * return (
+ *   <>
+ *     {error && "there was a problem loading the image"}
+ *     <canvas ref={ref} />
+ *   </>
+ * ```
+ */
 function useImage(imageOrUrl, crossOrigin) {
@@ -10,0 +35,0 @@ var _useState = (0, _react.useState)({

es/useInterval.d.ts

@@ -0,2 +1,8 @@
+/**
+ * Creates a `setInterval` that is properly cleaned up when a component unmounted
+ *
+ * @param fn an function run on each interval
+ * @param ms The milliseconds duration of the interval
+ */
 declare function useInterval(fn: () => void, ms: number): void;
 export default useInterval;

es/useInterval.js

@@ -12,2 +12,9 @@ "use strict";
 
+/**
+ * Creates a pasuable `setInterval` that is properly cleaned up when a component unmounted
+ *
+ * @param fn an function run on each interval
+ * @param ms The milliseconds duration of the interval
+ * @param paused Whether or not the interval is currently running
+ */
 function useInterval(fn, ms, paused) {
@@ -14,0 +21,0 @@ if (paused === void 0) {

es/useMergeState.d.ts

 declare type Updater<TState> = (state: TState) => Partial<TState> | null;
+/**
+ * Updates state, partial updates are merged into existing state values
+ */
 export declare type MergeStateSetter<TState> = (update: Updater<TState> | Partial<TState> | null) => void;
+/**
+ * Mimics a React class component's state model, of having a single unified
+ * `state` object and an updater that merges updates into the existing state, as
+ * opposed to replacing it.
+ *
+ * ```js
+ * const [state, setState] = useMergeState({ name: 'Betsy', age: 24 })
+ *
+ * setState({ name: 'Johan' }) // { name: 'Johan', age: 24 }
+ *
+ * setState(state => ({ age: state.age + 10 })) // { name: 'Johan', age: 34 }
+ * ```
+ *
+ * @param initialState The initial state object
+ */
 export default function useMergeState<TState extends {}>(initialState: TState): [TState, MergeStateSetter<TState>];
 export {};

es/useMergeState.js

@@ -10,2 +10,17 @@ "use strict";
 
+/**
+ * Mimics a React class component's state model, of having a single unified
+ * `state` object and an updater that merges updates into the existing state, as
+ * opposed to replacing it.
+ *
+ * ```js
+ * const [state, setState] = useMergeState({ name: 'Betsy', age: 24 })
+ *
+ * setState({ name: 'Johan' }) // { name: 'Johan', age: 24 }
+ *
+ * setState(state => ({ age: state.age + 10 })) // { name: 'Johan', age: 34 }
+ * ```
+ *
+ * @param initialState The initial state object
+ */
 function useMergeState(initialState) {
@@ -12,0 +27,0 @@ var _useState = (0, _react.useState)(initialState),

es/useMounted.d.ts

@@ -0,1 +1,8 @@
+/**
+ * Track whether a component is current mounted. Generally less preferable than
+ * properlly canceling effects so they don't run after a component is unmounted,
+ * but helpful in cases where that isn't feasible, such as a `Promise` resolution.
+ *
+ * @returns a function that returns the current isMounted state of the component
+ */
 export default function useMounted(): () => boolean;

es/useMounted.js

@@ -8,2 +8,9 @@ "use strict";
 
+/**
+ * Track whether a component is current mounted. Generally less preferable than
+ * properlly canceling effects so they don't run after a component is unmounted,
+ * but helpful in cases where that isn't feasible, such as a `Promise` resolution.
+ *
+ * @returns a function that returns the current isMounted state of the component
+ */
 function useMounted() {
@@ -10,0 +17,0 @@ var mounted = (0, _react.useRef)(true);

es/usePrevious.d.ts

@@ -0,1 +1,18 @@
+/**
+ * Store the last of some value. Tracked via a `Ref` only updating it
+ * after the component renders.
+ *
+ * Helpful if you need to compare a prop value to it's previous value during render.
+ *
+ * ```ts
+ * function Component(props) {
+ *   const lastProps = usePrevious(props)
+ *
+ *   if (lastProps.foo !== props.foo)
+ *     resetValueFromProps(props.foo)
+ * }
+ * ```
+ *
+ * @param value the value to track
+ */
 export default function usePrevious<T>(value: T): T | null;

es/usePrevious.js

@@ -8,2 +8,19 @@ "use strict";
 
+/**
+ * Store the last of some value. Tracked via a `Ref` only updating it
+ * after the component renders.
+ *
+ * Helpful if you need to compare a prop value to it's previous value during render.
+ *
+ * ```ts
+ * function Component(props) {
+ *   const lastProps = usePrevious(props)
+ *
+ *   if (lastProps.foo !== props.foo)
+ *     resetValueFromProps(props.foo)
+ * }
+ * ```
+ *
+ * @param value the value to track
+ */
 function usePrevious(value) {
@@ -10,0 +27,0 @@ var ref = (0, _react.useRef)(null);

es/useResizeObserver.d.ts

@@ -7,2 +7,20 @@ export interface Rect {
 }
+/**
+ * Efficiently observe size changes on an element. Depends on the `ResizeObserver` api,
+ * and polyfills are needed in older browsers.
+ *
+ * ```ts
+ * const [ref, attachRef] = useCallbackRef(null);
+ *
+ * const rect = useResizeObserver(ref);
+ *
+ * return (
+ *  <div ref={attachRef}>
+ *    {JSON.stringify(rect)}
+ *  </div>
+ * )
+ * ```
+ *
+ * @param element The DOM element to observe
+ */
 export default function useResizeObserver<TElement extends Element>(element: TElement | null | undefined): Rect | null;

es/useResizeObserver.js

@@ -20,3 +20,22 @@ "use strict";
 }
+/**
+ * Efficiently observe size changes on an element. Depends on the `ResizeObserver` api,
+ * and polyfills are needed in older browsers.
+ *
+ * ```ts
+ * const [ref, attachRef] = useCallbackRef(null);
+ *
+ * const rect = useResizeObserver(ref);
+ *
+ * return (
+ *  <div ref={attachRef}>
+ *    {JSON.stringify(rect)}
+ *  </div>
+ * )
+ * ```
+ *
+ * @param element The DOM element to observe
+ */
 
+
 function useResizeObserver(element) {
@@ -23,0 +42,0 @@ var _useState = (0, _react.useState)(null),

index.js

@@ -5,2 +5,6 @@ "use strict";
 
+var _useCallbackRef = _interopRequireDefault(require("./useCallbackRef"));
+
+exports.useCallbackRef = _useCallbackRef.default;
+
 var _useCommittedRef = _interopRequireDefault(require("./useCommittedRef"));
@@ -50,2 +54,6 @@
 
+var _useResizeObserver = _interopRequireDefault(require("./useResizeObserver"));
+
+exports.useResizeObserver = _useResizeObserver.default;
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

package.json

 {
   "name": "@restart/hooks",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "main": "index.js",
@@ -5,0 +5,0 @@ "types": "index.d.ts",

useCommittedRef.js

@@ -8,2 +8,11 @@ "use strict";
 
+/**
+ * Creates a `Ref` whose value is updated in an effect, ensuring the most recent
+ * value is the one rendered with. Generally only required for Concurrent mode usage
+ * where previous work in `render()` may be discarded befor being used.
+ *
+ * This is safe to access in an event handler.
+ *
+ * @param value The `Ref` value
+ */
 function useCommittedRef(value) {
@@ -10,0 +19,0 @@ var ref = (0, _react.useRef)(value);

useEventListener.js

@@ -12,2 +12,11 @@ "use strict";
 
+/**
+ * Attaches an event handler outside directly to specified DOM element
+ * bypassing the react synthetic event system.
+ *
+ * @param element The target to listen for events on
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
 function useEventListener(element, event, listener, capture) {
@@ -14,0 +23,0 @@ if (capture === void 0) {

useGlobalListener.js

@@ -10,3 +10,17 @@ "use strict";
 
-function useGlobalListener(event, listener, capture) {
+/**
+ * Attaches an event handler outside directly to the `document`,
+ * bypassing the react synthetic event system.
+ *
+ * ```ts
+ * useGlobalListener('keydown', (event) => {
+ *  console.log(event.key)
+ * })
+ * ```
+ *
+ * @param event The DOM event name
+ * @param handler An event handler
+ * @param capture Whether or not to listen during the capture event phase
+ */
+function useGlobalListener(event, handler, capture) {
   if (capture === void 0) {
@@ -16,3 +30,3 @@ capture = false;
 
-  return (0, _useEventListener.default)(document, event, listener, capture);
+  return (0, _useEventListener.default)(document, event, handler, capture);
 }

useImage.js

@@ -8,2 +8,27 @@ "use strict";
 
+/**
+ * Fetch and load an image for programatic use such as in a `<canvas>` element.
+ *
+ * @param imageOrUrl The `HtmlImageElement` or image url to load
+ * @param crossOrigin The `crossorigin` attribute to set
+ *
+ * ```ts
+ * const { image, error } = useImage('/static/kittens.png')
+ * const ref = useRef<HTMLCanvasElement>()
+ *
+ * useEffect(() => {
+ *   const ctx = ref.current.getContext('2d')
+ *
+ *   if (image) {
+ *     ctx.drawImage(image, 0, 0)
+ *   }
+ * }, [ref, image])
+ *
+ * return (
+ *   <>
+ *     {error && "there was a problem loading the image"}
+ *     <canvas ref={ref} />
+ *   </>
+ * ```
+ */
 function useImage(imageOrUrl, crossOrigin) {
@@ -10,0 +35,0 @@ var _useState = (0, _react.useState)({

useInterval.js

@@ -12,2 +12,9 @@ "use strict";
 
+/**
+ * Creates a pasuable `setInterval` that is properly cleaned up when a component unmounted
+ *
+ * @param fn an function run on each interval
+ * @param ms The milliseconds duration of the interval
+ * @param paused Whether or not the interval is currently running
+ */
 function useInterval(fn, ms, paused) {
@@ -14,0 +21,0 @@ if (paused === void 0) {

useMergeState.js

@@ -10,2 +10,17 @@ "use strict";
 
+/**
+ * Mimics a React class component's state model, of having a single unified
+ * `state` object and an updater that merges updates into the existing state, as
+ * opposed to replacing it.
+ *
+ * ```js
+ * const [state, setState] = useMergeState({ name: 'Betsy', age: 24 })
+ *
+ * setState({ name: 'Johan' }) // { name: 'Johan', age: 24 }
+ *
+ * setState(state => ({ age: state.age + 10 })) // { name: 'Johan', age: 34 }
+ * ```
+ *
+ * @param initialState The initial state object
+ */
 function useMergeState(initialState) {
@@ -12,0 +27,0 @@ var _useState = (0, _react.useState)(initialState),

useMounted.js

@@ -8,2 +8,9 @@ "use strict";
 
+/**
+ * Track whether a component is current mounted. Generally less preferable than
+ * properlly canceling effects so they don't run after a component is unmounted,
+ * but helpful in cases where that isn't feasible, such as a `Promise` resolution.
+ *
+ * @returns a function that returns the current isMounted state of the component
+ */
 function useMounted() {
@@ -10,0 +17,0 @@ var mounted = (0, _react.useRef)(true);

usePrevious.js

@@ -8,2 +8,19 @@ "use strict";
 
+/**
+ * Store the last of some value. Tracked via a `Ref` only updating it
+ * after the component renders.
+ *
+ * Helpful if you need to compare a prop value to it's previous value during render.
+ *
+ * ```ts
+ * function Component(props) {
+ *   const lastProps = usePrevious(props)
+ *
+ *   if (lastProps.foo !== props.foo)
+ *     resetValueFromProps(props.foo)
+ * }
+ * ```
+ *
+ * @param value the value to track
+ */
 function usePrevious(value) {
@@ -10,0 +27,0 @@ var ref = (0, _react.useRef)(null);

useResizeObserver.js

@@ -20,3 +20,22 @@ "use strict";
 }
+/**
+ * Efficiently observe size changes on an element. Depends on the `ResizeObserver` api,
+ * and polyfills are needed in older browsers.
+ *
+ * ```ts
+ * const [ref, attachRef] = useCallbackRef(null);
+ *
+ * const rect = useResizeObserver(ref);
+ *
+ * return (
+ *  <div ref={attachRef}>
+ *    {JSON.stringify(rect)}
+ *  </div>
+ * )
+ * ```
+ *
+ * @param element The DOM element to observe
+ */
 
+
 function useResizeObserver(element) {
@@ -23,0 +42,0 @@ var _useState = (0, _react.useState)(null),

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

41536

increased by33.95%

Lines of code

1132

increased by48.56%

Worsened metrics

Number of package files

48

decreased by-15.79%

No dependency changes