@trackunit/react-components 1.22.17 → 1.22.18

package/index.cjs.js

@@ -333,7 +333,7 @@ const Tag = ({ className, "data-testid": dataTestId, children, size = "medium",
  * A component used to display the package name and version in the Storybook docs.
  */
 const PackageNameStoryComponent = ({ packageJSON }) => {
-    return (jsxRuntime.jsxs("div", { className: "flex gap-2", children: [jsxRuntime.jsx(Tag, { color: "neutral", children: packageJSON?.name }), jsxRuntime.jsxs(Tag, { color: "neutral", children: ["v", packageJSON?.version] })] }));
+    return (jsxRuntime.jsxs("div", { className: "flex gap-2", children: [jsxRuntime.jsx(Tag, { color: "neutral", children: packageJSON?.name }), packageJSON?.version ? jsxRuntime.jsxs(Tag, { color: "neutral", children: ["v", packageJSON.version] }) : null] }));
 };
 
 const docs = {
@@ -1352,11 +1352,16 @@ const getViewportBreakpointState = () => {
     }), { ...defaultBreakpointState });
 };
 /**
- * A custom React hook that provides real-time information about the current viewport size.
- * ! Consider using `useContainerBreakpoints` instead, and only use this when you need to actually react to the viewport size, not the container size.
+ * Returns real-time boolean flags for each design-token breakpoint based on viewport width.
  *
- * This hook listens to changes in the viewport size and returns an object with boolean values
- * indicating which breakpoints are currently active.
+ * **When to use:**
+ * - Use `useViewportBreakpoints` when you need to respond to the **full viewport width**
+ *   — for example, toggling a mobile navigation drawer or switching a global layout shell.
+ * - **Prefer `useContainerBreakpoints`** for component-level responsiveness, as it
+ *   responds to the parent container's width and works correctly when a component appears
+ *   in different layout contexts (sidebar, main content, widget).
+ * - Pass `{ skip: true }` when you only need the initial value and don't want ongoing
+ *   `matchMedia` listeners.
  *
  * @param {object} [options] - Configuration options
  * @param {boolean} [options.skip] - Whether to skip observing for viewport changes (default: false)
@@ -4327,14 +4332,43 @@ const Highlight = ({ className, "data-testid": dataTestId, children, size = "sma
 Highlight.displayName = "Highlight";
 
 /**
- * The useDebounce hook works like useState, but adds a delay where previous values will be ignored.
+ * Returns a debounced copy of `value`: it updates only after `delay` ms without further
+ * changes. Pass whatever changes on each keystroke, tick, or prop update; this hook only
+ * delays the value you read back — it does not own the source of truth or expose a setter.
+ *
+ * ### When to use
+ * Use `useDebounce` to delay expensive operations triggered by rapidly changing values —
+ * search inputs, filter fields, resize observers, or any value that changes faster than
+ * you want to react to it.
+ *
+ * ### When not to use
+ * - When you need to debounce a callback rather than a value — wrap the callback in a
+ *   `setTimeout` / `useMemo` pattern instead.
+ * - For throttling (fixed-interval updates) — debounce waits for inactivity, throttle
+ *   fires at intervals.
  *
  * @template TValue
- * @param {TValue} value The value to set
+ * @param {TValue} value The value to debounce (the fast-changing source)
  * @param {UseDebounceOptions<TValue>} options The debounce options
  * @param {(debouncedValue: TValue) => void} options.onBounce Callback when the value is debounced
  * @param {number} options.delay The debounce time
- * @returns {TValue} The latest value received
+ * @returns {TValue} The debounced value (lags behind `value` until the quiet period elapses)
+ * @example
+ * ```tsx
+ * // Debounce a search input before firing a query
+ * const [search, setSearch] = useState("");
+ * const debouncedSearch = useDebounce(search, { delay: 300 });
+ *
+ * const { data } = useQuery(SearchDocument, {
+ *   variables: { query: debouncedSearch },
+ * });
+ *
+ * // With an onBounce callback (e.g. for analytics)
+ * const debouncedValue = useDebounce(inputValue, {
+ *   delay: 500,
+ *   onBounce: value => logEvent("SearchPerformed", { query: value }),
+ * });
+ * ```
  */
 const useDebounce = (value, { onBounce, delay = 500 } = {}) => {
     const [debouncedValue, setDebouncedValue] = react.useState(value);
@@ -10881,6 +10915,25 @@ const useWebStorage = (storage, { key, defaultState, schema, migration, onValida
  * @param options.onValidationFailed - Optional error callback.
  * @param options.onValidationSuccessful - Optional success callback.
  * @returns {Array} A tuple of [state, setState, reset].
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { useLocalStorage } from "@trackunit/react-components";
+ *
+ * const preferencesSchema = z.object({
+ *   theme: z.enum(["light", "dark"]),
+ *   lastVisited: z.date(),
+ * });
+ *
+ * const [preferences, setPreferences, reset] = useLocalStorage({
+ *   key: "user-preferences",
+ *   defaultState: { theme: "light", lastVisited: new Date() },
+ *   schema: preferencesSchema,
+ * });
+ *
+ * setPreferences(prev => ({ ...prev, theme: "dark" }));
+ * reset(); // clear the stored value and fall back to defaultState
+ * ```
  */
 const useLocalStorage = (options) => useWebStorage(globalThis.localStorage, options);
 

package/index.esm.js

@@ -331,7 +331,7 @@ const Tag = ({ className, "data-testid": dataTestId, children, size = "medium",
  * A component used to display the package name and version in the Storybook docs.
  */
 const PackageNameStoryComponent = ({ packageJSON }) => {
-    return (jsxs("div", { className: "flex gap-2", children: [jsx(Tag, { color: "neutral", children: packageJSON?.name }), jsxs(Tag, { color: "neutral", children: ["v", packageJSON?.version] })] }));
+    return (jsxs("div", { className: "flex gap-2", children: [jsx(Tag, { color: "neutral", children: packageJSON?.name }), packageJSON?.version ? jsxs(Tag, { color: "neutral", children: ["v", packageJSON.version] }) : null] }));
 };
 
 const docs = {
@@ -1350,11 +1350,16 @@ const getViewportBreakpointState = () => {
     }), { ...defaultBreakpointState });
 };
 /**
- * A custom React hook that provides real-time information about the current viewport size.
- * ! Consider using `useContainerBreakpoints` instead, and only use this when you need to actually react to the viewport size, not the container size.
+ * Returns real-time boolean flags for each design-token breakpoint based on viewport width.
  *
- * This hook listens to changes in the viewport size and returns an object with boolean values
- * indicating which breakpoints are currently active.
+ * **When to use:**
+ * - Use `useViewportBreakpoints` when you need to respond to the **full viewport width**
+ *   — for example, toggling a mobile navigation drawer or switching a global layout shell.
+ * - **Prefer `useContainerBreakpoints`** for component-level responsiveness, as it
+ *   responds to the parent container's width and works correctly when a component appears
+ *   in different layout contexts (sidebar, main content, widget).
+ * - Pass `{ skip: true }` when you only need the initial value and don't want ongoing
+ *   `matchMedia` listeners.
  *
  * @param {object} [options] - Configuration options
  * @param {boolean} [options.skip] - Whether to skip observing for viewport changes (default: false)
@@ -4325,14 +4330,43 @@ const Highlight = ({ className, "data-testid": dataTestId, children, size = "sma
 Highlight.displayName = "Highlight";
 
 /**
- * The useDebounce hook works like useState, but adds a delay where previous values will be ignored.
+ * Returns a debounced copy of `value`: it updates only after `delay` ms without further
+ * changes. Pass whatever changes on each keystroke, tick, or prop update; this hook only
+ * delays the value you read back — it does not own the source of truth or expose a setter.
+ *
+ * ### When to use
+ * Use `useDebounce` to delay expensive operations triggered by rapidly changing values —
+ * search inputs, filter fields, resize observers, or any value that changes faster than
+ * you want to react to it.
+ *
+ * ### When not to use
+ * - When you need to debounce a callback rather than a value — wrap the callback in a
+ *   `setTimeout` / `useMemo` pattern instead.
+ * - For throttling (fixed-interval updates) — debounce waits for inactivity, throttle
+ *   fires at intervals.
  *
  * @template TValue
- * @param {TValue} value The value to set
+ * @param {TValue} value The value to debounce (the fast-changing source)
  * @param {UseDebounceOptions<TValue>} options The debounce options
  * @param {(debouncedValue: TValue) => void} options.onBounce Callback when the value is debounced
  * @param {number} options.delay The debounce time
- * @returns {TValue} The latest value received
+ * @returns {TValue} The debounced value (lags behind `value` until the quiet period elapses)
+ * @example
+ * ```tsx
+ * // Debounce a search input before firing a query
+ * const [search, setSearch] = useState("");
+ * const debouncedSearch = useDebounce(search, { delay: 300 });
+ *
+ * const { data } = useQuery(SearchDocument, {
+ *   variables: { query: debouncedSearch },
+ * });
+ *
+ * // With an onBounce callback (e.g. for analytics)
+ * const debouncedValue = useDebounce(inputValue, {
+ *   delay: 500,
+ *   onBounce: value => logEvent("SearchPerformed", { query: value }),
+ * });
+ * ```
  */
 const useDebounce = (value, { onBounce, delay = 500 } = {}) => {
     const [debouncedValue, setDebouncedValue] = useState(value);
@@ -10879,6 +10913,25 @@ const useWebStorage = (storage, { key, defaultState, schema, migration, onValida
  * @param options.onValidationFailed - Optional error callback.
  * @param options.onValidationSuccessful - Optional success callback.
  * @returns {Array} A tuple of [state, setState, reset].
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { useLocalStorage } from "@trackunit/react-components";
+ *
+ * const preferencesSchema = z.object({
+ *   theme: z.enum(["light", "dark"]),
+ *   lastVisited: z.date(),
+ * });
+ *
+ * const [preferences, setPreferences, reset] = useLocalStorage({
+ *   key: "user-preferences",
+ *   defaultState: { theme: "light", lastVisited: new Date() },
+ *   schema: preferencesSchema,
+ * });
+ *
+ * setPreferences(prev => ({ ...prev, theme: "dark" }));
+ * reset(); // clear the stored value and fall back to defaultState
+ * ```
  */
 const useLocalStorage = (options) => useWebStorage(globalThis.localStorage, options);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.22.17",
+  "version": "1.22.18",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -13,10 +13,10 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.11.108",
-    "@trackunit/css-class-variance-utilities": "1.11.111",
-    "@trackunit/shared-utils": "1.13.111",
-    "@trackunit/ui-icons": "1.11.107",
+    "@trackunit/ui-design-tokens": "1.11.109",
+    "@trackunit/css-class-variance-utilities": "1.11.112",
+    "@trackunit/shared-utils": "1.13.112",
+    "@trackunit/ui-icons": "1.11.108",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
     "dequal": "^2.0.3",

package/src/hooks/localStorage/useLocalStorage.d.ts

@@ -12,5 +12,24 @@ import type { WebStorageCallbacks, WebStorageOptions } from "./types";
  * @param options.onValidationFailed - Optional error callback.
  * @param options.onValidationSuccessful - Optional success callback.
  * @returns {Array} A tuple of [state, setState, reset].
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { useLocalStorage } from "@trackunit/react-components";
+ *
+ * const preferencesSchema = z.object({
+ *   theme: z.enum(["light", "dark"]),
+ *   lastVisited: z.date(),
+ * });
+ *
+ * const [preferences, setPreferences, reset] = useLocalStorage({
+ *   key: "user-preferences",
+ *   defaultState: { theme: "light", lastVisited: new Date() },
+ *   schema: preferencesSchema,
+ * });
+ *
+ * setPreferences(prev => ({ ...prev, theme: "dark" }));
+ * reset(); // clear the stored value and fall back to defaultState
+ * ```
  */
 export declare const useLocalStorage: <TState>(options: WebStorageOptions<TState> & WebStorageCallbacks<TState>) => readonly [TState, Dispatch<SetStateAction<TState>>, () => void];

package/src/hooks/useDebounce.d.ts

@@ -3,14 +3,43 @@ type UseDebounceOptions<TValue> = {
     delay?: number;
 };
 /**
- * The useDebounce hook works like useState, but adds a delay where previous values will be ignored.
+ * Returns a debounced copy of `value`: it updates only after `delay` ms without further
+ * changes. Pass whatever changes on each keystroke, tick, or prop update; this hook only
+ * delays the value you read back — it does not own the source of truth or expose a setter.
+ *
+ * ### When to use
+ * Use `useDebounce` to delay expensive operations triggered by rapidly changing values —
+ * search inputs, filter fields, resize observers, or any value that changes faster than
+ * you want to react to it.
+ *
+ * ### When not to use
+ * - When you need to debounce a callback rather than a value — wrap the callback in a
+ *   `setTimeout` / `useMemo` pattern instead.
+ * - For throttling (fixed-interval updates) — debounce waits for inactivity, throttle
+ *   fires at intervals.
  *
  * @template TValue
- * @param {TValue} value The value to set
+ * @param {TValue} value The value to debounce (the fast-changing source)
  * @param {UseDebounceOptions<TValue>} options The debounce options
  * @param {(debouncedValue: TValue) => void} options.onBounce Callback when the value is debounced
  * @param {number} options.delay The debounce time
- * @returns {TValue} The latest value received
+ * @returns {TValue} The debounced value (lags behind `value` until the quiet period elapses)
+ * @example
+ * ```tsx
+ * // Debounce a search input before firing a query
+ * const [search, setSearch] = useState("");
+ * const debouncedSearch = useDebounce(search, { delay: 300 });
+ *
+ * const { data } = useQuery(SearchDocument, {
+ *   variables: { query: debouncedSearch },
+ * });
+ *
+ * // With an onBounce callback (e.g. for analytics)
+ * const debouncedValue = useDebounce(inputValue, {
+ *   delay: 500,
+ *   onBounce: value => logEvent("SearchPerformed", { query: value }),
+ * });
+ * ```
  */
 export declare const useDebounce: <TValue>(value: TValue, { onBounce, delay }?: UseDebounceOptions<TValue>) => TValue;
 export {};

package/src/hooks/useViewportBreakpoints.d.ts

@@ -3,11 +3,16 @@ type UseViewportBreakpointsOptions = {
     skip?: boolean;
 };
 /**
- * A custom React hook that provides real-time information about the current viewport size.
- * ! Consider using `useContainerBreakpoints` instead, and only use this when you need to actually react to the viewport size, not the container size.
+ * Returns real-time boolean flags for each design-token breakpoint based on viewport width.
  *
- * This hook listens to changes in the viewport size and returns an object with boolean values
- * indicating which breakpoints are currently active.
+ * **When to use:**
+ * - Use `useViewportBreakpoints` when you need to respond to the **full viewport width**
+ *   — for example, toggling a mobile navigation drawer or switching a global layout shell.
+ * - **Prefer `useContainerBreakpoints`** for component-level responsiveness, as it
+ *   responds to the parent container's width and works correctly when a component appears
+ *   in different layout contexts (sidebar, main content, widget).
+ * - Pass `{ skip: true }` when you only need the initial value and don't want ongoing
+ *   `matchMedia` listeners.
  *
  * @param {object} [options] - Configuration options
  * @param {boolean} [options.skip] - Whether to skip observing for viewport changes (default: false)