@reykjavik/webtools 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.2.9
+
+_2025-09-30_
+
+- `@reykjavik/webtools/next/vanillaExtract`:
+  - feat: Make `vanillaVars` return a type-safe `setVars()` helper to avoid
+    offending VSCode's CSS syntax parser too much.
+
+## 0.2.8
+
+_2025-09-17_
+
+- `@reykjavik/webtools/async`:
+  - feat: Add `debounce` and `throttle` helpers
+- `@reykjavik/webtools/hooks` (new module):
+  - feat: Add `useDebounced` and `useThrottled` hooks
+
 ## 0.2.7
 
 _2025-09-01_

package/README.md

@@ -29,6 +29,11 @@ bun add @reykjavik/webtools
 - [`@reykjavik/webtools/async`](#reykjavikwebtoolsasync)
   - [`promiseAllObject`](#promiseallobject)
   - [`maxWait`](#maxwait)
+  - [`debounce`](#debounce)
+  - [`throttle`](#throttle)
+- [`@reykjavik/webtools/hoooks`](#reykjavikwebtoolshoooks)
+  - [`useDebounced`](#usedebounced)
+  - [`useThrottled`](#usethrottled)
 - [`@reykjavik/webtools/errorhandling`](#reykjavikwebtoolserrorhandling)
   - [`asError`](#aserror)
   - [`Result` Singleton](#result-singleton)
@@ -369,6 +374,188 @@ console.log(posts?.reason); // undefined | unknown
 
 ---
 
+### `debounce`
+
+**Syntax:**
+`debounce<A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): ((...args: A) => void) & { cancel: (finish?: boolean) => void; }`
+
+Returns a debounced function that only runs after `delay` milliseconds of
+quiet-time, and can optionally be made to run `immediate`ly on first call
+before dbouncing subsequent calls.
+
+```ts
+import { debounce } from '@reykjavik/webtools/async';
+
+// Basic usage:
+const sayHello = debounce((namme: string) => {
+  console.log('Hello ' + name);
+}, 200);
+
+sayHello('Alice');
+sayHello('Bob');
+sayHello('Charlie');
+sayHello('Dorothy');
+// Only "Hello Dorothy" is logged, 200ms after the last call
+
+// With `immediate` param set to true:
+const sayHi = debounce(
+  (namme: string) => console.log('Hi ' + name),
+  200,
+  true
+);
+sayHi('Alice');
+sayHi('Bob');
+sayHi('Charlie');
+sayHi('Dorothy');
+// "Hi Alice" is logged immediately
+// Then "Hi Dorothy" is logged, 200ms after the last call
+```
+
+The returned function has a nice `.cancel()` method, which can optionally
+invoke the function before cancelling, if it had a debounce pending.
+
+```ts
+sayHello('Erica');
+sayHello('Fiona');
+sayHello.cancel();
+// Nothing is logged because the debounce was cancelled
+
+sayHello('George');
+sayHello('Harold');
+sayHello.cancel(true); // `finish` parmeter is true
+// "Hello Harold" is logged immediately because it was pending
+```
+
+---
+
+### `throttle`
+
+**Syntax:**
+`throttle<A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): ((...args: A) => void) & { finish: (cancel?: boolean) => void; }`
+
+Returns a throttled function that never runs more often than every `delay`
+milliseconds. It can optionally made to `skipFirst` invocation.
+
+```ts
+import { throttle } from '@reykjavik/webtools/async';
+
+// Basic usage:
+const sayHello = throttle((name: string) => {
+  console.log('Hello ' + name);
+}, 200);
+
+sayHello('Alice');
+sayHello('Bob');
+sayHello('Charlie');
+sayHello('Dorothy');
+// Only "Hello Alice" is logged immediately. The other calls were throttled.
+
+// With `skipFirst` param set to true:
+const sayHi = throttle(
+  (name: string) => console.log('Hi ' + name),
+  200,
+  true
+);
+sayHi('Alice');
+sayHi('Bob');
+sayHi('Charlie');
+sayHi('Dorothy');
+// Nothing is logged. The first call was skipped, and the rest were throttled.
+```
+
+The returned function also has a nice `.finish()` method to reset the throttle
+timer. By default it instantly invokes the function, if the last call was
+throttled (skipped)-.
+
+```ts
+sayHello('Erica');
+sayHello('Fiona');
+sayHello.finish();
+// "Hello Fiona" is logged immediately because it was pending
+
+sayHello('George');
+sayHello('Harold');
+sayHello.finish(true); // `cancel` parmeter is true
+// Nothing is logged because the pending call was cancelled
+```
+
+---
+
+## `@reykjavik/webtools/hoooks`
+
+Some useful React hooks.
+
+### `useDebounced`
+
+**Syntax:**
+`useDebounced<A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): ((...args: A) => void) & { cancel: (finish?: boolean) => void; }`
+
+Returns a stable debounced function that invokes the supplied function after
+the specified delay. When the component unmounts, any pending (debounced)
+calls are automatically cancelled.
+
+**NOTE:** The supplied callback does not need to be memoized. The debouncer
+will always invoke the last supplied version.
+
+```ts
+import { useDebounced } from '@reykjavik/webtools/hoooks';
+
+const MyComponent = () => {
+  const renderDate = new Date();
+  const debouncedSearch = useDebounced((query: string) => {
+    console.log('Searching for:', query, 'at', renderDate.toISOString());
+  }, 200);
+  return (
+    <input
+      type="text"
+      onChange={(e) => {
+        debouncedSearch(e.currentTarget.value);
+      }}
+    />
+  );
+};
+```
+
+See [`debounce`](#debounce) for more details about the parameters and the
+returned debounced function's `.cancel()` method.
+
+### `useThrottled`
+
+**Syntax:**
+`useThrottled<A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): ((...args: A) => void) & { finish: (cancel?: boolean) => void; }`
+
+Returns a stable throttler function that throttles the supplied function.
+
+**NOTE:** The supplied callback does not need to be memoized. The throttler
+will always invoke the last supplied version.
+
+```ts
+import { useThrottled } from '@reykjavik/webtools/hoooks';
+
+const MyComponent = () => {
+  const renderDate = new Date();
+  const throttledReportPosition = useThrottled((x: number, y: number) => {
+    console.log('Mouse position:', x, ',', y, 'at', renderDate.toISOString());
+  }, 200);
+
+  return (
+    <div
+      style={{ width: '300px', height: '300px', background: '#eee' }}
+      onMouseMove={(e) => {
+        throttledReportPosition(e.clientX, e.clientY);
+      }}
+    >
+      Move your mouse here.
+    </div>
+  );
+};
+```
+
+See [`throttle`](#throttle) for more details about the parameters and the
+returned throttled function's `.finish()` method.
+
+---
+
 ## `@reykjavik/webtools/errorhandling`
 
 A small set of lightweight tools for handling errors and promises in a safer,
@@ -660,9 +847,11 @@ editor), but there's a brief summary:
   `scriptUrl` prop).
 - `scriptUrl?: string` — The full SiteImprove analytics script URL.
   (alternative to `accountId` prop).
-- `hasConsented?: boolean` — Manual GDPR 'analytics' consent flag. Allows hard
-  opt-out, but defers to [`CookieHubProvider` values](#usecookiehubconsent) if
-  they are available.
+- `hasConsented?: boolean` — Manual GDPR 'analytics' consent flag. A `false`
+  value allows hard opt-out, but defers to
+  [`CookieHubProvider` values](#usecookiehubconsent) if they are available.
+  Defaults to `undefined` which means "ask CookieHub if available, otherwise
+  no".
 - `onLoad?: (e: unknown) => void` — Fires when the script has loaded.
 - `onError?: (e: unknown) => void` — Fires if loading the script failed.
 
@@ -999,21 +1188,21 @@ import {
   vanillaGlobal,
 } from '@reykjavik/webtools/vanillaExtract';
 
-export const { varPrimaryColor, varSecondaryColor } = vanillaVars(
+const { varPrimaryColor, varSecondaryColor, setVars } = vanillaVars(
   'primaryColor',
   'secondaryColor'
 );
 
-vanillaGlobal(`
-  :root {
-    ${varPrimaryColor}: #ff0000;
-    ${varSecondaryColor}: #00ff00;
-  }
-  body {
-    background-color: var(${varPrimaryColor});
-    color: var(${varSecondaryColor});
-  }
-`);
+export { varPrimaryColor, varSecondaryColor };
+
+export const wrapper = vanillaClass(`
+  ${setVars({
+    primaryColor: '#ff0000',
+    secondaryColor: '#00ff00',
+  })}
+  background-color: var(${varPrimaryColor});
+  color: var(${varSecondaryColor});
+ `);
 ```
 
 …and then in your component:
@@ -1026,6 +1215,7 @@ import * as cl from './someFile.css.ts';
 export function MyComponent() {
   return (
     <div
+      className={cl.wrapper}
       style={{
         [cl.varPrimaryColor]: 'yellow',
         [cl.varSecondaryColor]: 'blue',

package/async.d.ts

@@ -31,4 +31,43 @@ export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, pr
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#promiseallobject
  */
 export declare const promiseAllObject: <T extends PlainObj>(promisesMap: T) => Promise<{ -readonly [K in keyof T]: Awaited<T[K]>; }>;
+type Cancellable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Cancels any pending invocation of the debounced function.  \
+     * If `finish` is true and if a debounce is pending, the function is invoked
+     * before cancelling.
+     */
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+export declare const debounce: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): Cancellable<A>;
+    d(delay: number, immediate?: boolean): Cancellable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
+type Finishable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Immediately invokes the function if there is a pending throttle and its last
+     * invoication was throttled (cancelled).  \
+     * If `cancel` is true then only the timer is reset without invoking function.
+     */
+    finish(cancel?: boolean): void;
+};
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+export declare const throttle: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): Finishable<A>;
+    d(delay: number, skipFirst?: boolean): Finishable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
 export {};

package/async.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
+exports.throttle = exports.debounce = exports.promiseAllObject = exports.addLag = exports.sleep = void 0;
 exports.maxWait = maxWait;
 /**
  * Simple sleep function. Returns a promise that resolves after `length`
@@ -79,3 +79,107 @@ const promiseAllObject = (promisesMap) => Promise.all(Object.values(promisesMap)
     return resolvedMap;
 });
 exports.promiseAllObject = promiseAllObject;
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const debounce = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    let timeout;
+    let _args;
+    let _this;
+    const debouncedFn = function (...args) {
+        _args = args;
+        _this = this;
+        immediate && !timeout && func.apply(_this, _args);
+        timeout && clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            debouncedFn.cancel(true);
+        }, delay);
+    };
+    debouncedFn.cancel = (finish) => {
+        timeout && clearTimeout(timeout);
+        finish && timeout && func.apply(_this, _args);
+        timeout = undefined;
+    };
+    return debouncedFn;
+};
+exports.debounce = debounce;
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myDebouncer = debounce.d(500);
+ *      myDebouncer(() => { alert('Hello world'); });
+ *      myDebouncer(() => { alert('I mean: Howdy world!'); });
+ *      myDebouncer((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+exports.debounce.d = (delay, immediate) => (0, exports.debounce)(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, immediate);
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+/*#__NO_SIDE_EFFECTS__*/
+const throttle = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately */
+skipFirst) => {
+    let timeout;
+    let throttled = 0;
+    let _args;
+    let _this;
+    const throttledFn = function (...args) {
+        _args = args;
+        _this = this;
+        if (!throttled) {
+            skipFirst ? throttled++ : func.apply(_this, _args);
+            timeout = setTimeout(throttledFn.finish, delay); // Go home TypeScript, you're drunk!
+        }
+        throttled++;
+    };
+    throttledFn.finish = (cancel) => {
+        timeout && clearTimeout(timeout);
+        !cancel && throttled && func.apply(_this, _args);
+        throttled = 0;
+    };
+    return throttledFn;
+};
+exports.throttle = throttle;
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myThrottler = throttle.d(500);
+ *      myThrottler(() => { alert('Hello world'); });
+ *      myThrottler(() => { alert('I mean: Howdy world!'); });
+ *      myThrottler((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+exports.throttle.d = (delay, skipFirst) => (0, exports.throttle)(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, skipFirst);

package/esm/async.d.ts

@@ -31,4 +31,43 @@ export declare function maxWait<PromiseMap extends PlainObj>(timeout: number, pr
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#promiseallobject
  */
 export declare const promiseAllObject: <T extends PlainObj>(promisesMap: T) => Promise<{ -readonly [K in keyof T]: Awaited<T[K]>; }>;
+type Cancellable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Cancels any pending invocation of the debounced function.  \
+     * If `finish` is true and if a debounce is pending, the function is invoked
+     * before cancelling.
+     */
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+export declare const debounce: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, immediate?: boolean): Cancellable<A>;
+    d(delay: number, immediate?: boolean): Cancellable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
+type Finishable<A extends Array<unknown>> = ((...args: A) => void) & {
+    /**
+     * Immediately invokes the function if there is a pending throttle and its last
+     * invoication was throttled (cancelled).  \
+     * If `cancel` is true then only the timer is reset without invoking function.
+     */
+    finish(cancel?: boolean): void;
+};
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+export declare const throttle: {
+    <A extends Array<unknown>>(func: (...args: A) => void, delay: number, skipFirst?: boolean): Finishable<A>;
+    d(delay: number, skipFirst?: boolean): Finishable<[fn: (...args: Array<any>) => void, ...args: any[]]>;
+};
 export {};

package/esm/async.js

@@ -72,3 +72,105 @@ export const promiseAllObject = (promisesMap) => Promise.all(Object.values(promi
     }
     return resolvedMap;
 });
+/**
+ * Returns a debounced function that only runs after `delay` milliseconds
+ * of quiet-time.  \
+ * The returned function also has a nice `.cancel()` method.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#debounce
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const debounce = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    let timeout;
+    let _args;
+    let _this;
+    const debouncedFn = function (...args) {
+        _args = args;
+        _this = this;
+        immediate && !timeout && func.apply(_this, _args);
+        timeout && clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            debouncedFn.cancel(true);
+        }, delay);
+    };
+    debouncedFn.cancel = (finish) => {
+        timeout && clearTimeout(timeout);
+        finish && timeout && func.apply(_this, _args);
+        timeout = undefined;
+    };
+    return debouncedFn;
+};
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myDebouncer = debounce.d(500);
+ *      myDebouncer(() => { alert('Hello world'); });
+ *      myDebouncer(() => { alert('I mean: Howdy world!'); });
+ *      myDebouncer((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+debounce.d = (delay, immediate) => debounce(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, immediate);
+/**
+ * Returns a throttled function that never runs more often than
+ * every `delay` milliseconds.  \
+ * The returned function also has a nice `.finish()` method to reset the
+ * throttle timer
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#throttle
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const throttle = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately */
+skipFirst) => {
+    let timeout;
+    let throttled = 0;
+    let _args;
+    let _this;
+    const throttledFn = function (...args) {
+        _args = args;
+        _this = this;
+        if (!throttled) {
+            skipFirst ? throttled++ : func.apply(_this, _args);
+            timeout = setTimeout(throttledFn.finish, delay); // Go home TypeScript, you're drunk!
+        }
+        throttled++;
+    };
+    throttledFn.finish = (cancel) => {
+        timeout && clearTimeout(timeout);
+        !cancel && throttled && func.apply(_this, _args);
+        throttled = 0;
+    };
+    return throttledFn;
+};
+/**
+ * Sugar to produce a dynamic debounced function that accepts its contents/behavior at call time.
+ *
+ * Usage:
+ * ```ts
+ *      const myThrottler = throttle.d(500);
+ *      myThrottler(() => { alert('Hello world'); });
+ *      myThrottler(() => { alert('I mean: Howdy world!'); });
+ *      myThrottler((name) => { alert('Wazzap ' + name); }, 'world');
+ * ```
+ *
+ * Not documented in README as its usefulness is still uncertain.
+ */
+throttle.d = (delay, skipFirst) => throttle(function (fn, ...args) {
+    fn.apply(this, args);
+}, delay, skipFirst);

package/esm/hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export declare const useDebounced: <A extends Array<unknown>>(
+/** The function to debounce */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait before running the function */
+delay: number, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate?: boolean) => ((...args: A) => void) & {
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export declare const useThrottled: <A extends Array<unknown>>(
+/** The function to throttle */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay: number, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst?: boolean) => ((...args: A) => void) & {
+    finish(cancel?: boolean): void;
+};

package/esm/hooks.js

@@ -0,0 +1,46 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { debounce, throttle } from './async.js';
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export const useDebounced = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    const fn = useRef();
+    fn.current = func;
+    const debouncedFunc = useMemo(() => debounce((...args) => fn.current(...args), delay, immediate), [delay, immediate]);
+    useEffect(() => debouncedFunc.cancel, [debouncedFunc]);
+    return debouncedFunc;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export const useThrottled = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst) => {
+    const fn = useRef();
+    fn.current = func;
+    const throttledFunc = useMemo(() => throttle((...args) => fn.current(...args), delay, skipFirst), [delay, skipFirst]);
+    // NOTE: We don't need to run throttled.finish() on unmount, as the default behavior is no-op.
+    return throttledFunc;
+};

package/esm/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./hooks.d.ts" />
 /// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />

package/esm/vanillaExtract.d.ts

@@ -37,5 +37,8 @@ export declare function vanillaClass(debugId: string, css: string | ClassNameCal
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#vanillacvars
  */
-export declare const vanillaVars: <T extends string>(...varNames: Array<T>) => Record<`var${Capitalize<T>}`, string>;
+export declare const vanillaVars: <T extends string>(...varNames: Array<T>) => Record<`var${Capitalize<T>}`, string> & {
+    /** Allows initializing all or some of the variables in CSS, without offending VSCode's CSS syntax parser too much. */
+    setVars: (vars: Partial<Record<T, unknown>>) => string;
+};
 export {};

package/esm/vanillaExtract.js

@@ -36,8 +36,12 @@ export function vanillaClass(cssOrDebugId, css) {
 export const vanillaVars = (...varNames) => {
     const id = vanillaClass(``);
     const vars = {};
+    vars.setVars = (vars) => Object.entries(vars)
+        .map(([name, value]) => `--${id}--${name}: ${value || ''};`)
+        .join('\n');
     for (const name of varNames) {
         vars[`var${capitalize(name)}`] = `--${id}--${name}`;
     }
     return vars;
 };
+const { varColor, varBg, setVars } = vanillaVars('color', 'bg');

package/hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+export declare const useDebounced: <A extends Array<unknown>>(
+/** The function to debounce */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait before running the function */
+delay: number, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate?: boolean) => ((...args: A) => void) & {
+    cancel(finish?: boolean): void;
+};
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+export declare const useThrottled: <A extends Array<unknown>>(
+/** The function to throttle */
+func: (...args: A) => void, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay: number, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst?: boolean) => ((...args: A) => void) & {
+    finish(cancel?: boolean): void;
+};

package/hooks.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useThrottled = exports.useDebounced = void 0;
+const react_1 = require("react");
+const async_js_1 = require("./async.js");
+/**
+ * Returns a stable debounced function that invokes the supplied function
+ * after the specified delay.  \
+ * When the component unmounts, any pending (debounced) calls are automatically cancelled.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The debouncer
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usedebounced
+ */
+const useDebounced = (
+/** The function to debounce */
+func, 
+/** The delay, in milliseconds, to wait before running the function */
+delay, 
+/** Whether to run the function at the start of the delay instead of the end */
+immediate) => {
+    const fn = (0, react_1.useRef)();
+    fn.current = func;
+    const debouncedFunc = (0, react_1.useMemo)(() => (0, async_js_1.debounce)((...args) => fn.current(...args), delay, immediate), [delay, immediate]);
+    (0, react_1.useEffect)(() => debouncedFunc.cancel, [debouncedFunc]);
+    return debouncedFunc;
+};
+exports.useDebounced = useDebounced;
+/**
+ * Returns a stable throttler function that throttles the supplied function.
+ *
+ * **NOTE:** The supplied callback does not need to be memoized. The throttler
+ * will always invoke the last supplied version.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#usethrottled
+ */
+const useThrottled = (
+/** The function to throttle */
+func, 
+/** The delay, in milliseconds, to wait between invocations. */
+delay, 
+/** Whether to skip the first invocation instead of running it immediately. */
+skipFirst) => {
+    const fn = (0, react_1.useRef)();
+    fn.current = func;
+    const throttledFunc = (0, react_1.useMemo)(() => (0, async_js_1.throttle)((...args) => fn.current(...args), delay, skipFirst), [delay, skipFirst]);
+    // NOTE: We don't need to run throttled.finish() on unmount, as the default behavior is no-op.
+    return throttledFunc;
+};
+exports.useThrottled = useThrottled;

package/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./hooks.d.ts" />
 /// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.2.7",
+	"version": "0.2.9",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",
@@ -44,6 +44,10 @@
 		"**/fixIcelandicLocale.js"
 	],
 	"exports": {
+		"./hooks": {
+			"import": "./esm/hooks.js",
+			"require": "./hooks.js"
+		},
 		".": {
 			"import": "./esm/index.js",
 			"require": "./index.js"

package/vanillaExtract.d.ts

@@ -37,5 +37,8 @@ export declare function vanillaClass(debugId: string, css: string | ClassNameCal
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#vanillacvars
  */
-export declare const vanillaVars: <T extends string>(...varNames: Array<T>) => Record<`var${Capitalize<T>}`, string>;
+export declare const vanillaVars: <T extends string>(...varNames: Array<T>) => Record<`var${Capitalize<T>}`, string> & {
+    /** Allows initializing all or some of the variables in CSS, without offending VSCode's CSS syntax parser too much. */
+    setVars: (vars: Partial<Record<T, unknown>>) => string;
+};
 export {};

package/vanillaExtract.js

@@ -42,9 +42,13 @@ function vanillaClass(cssOrDebugId, css) {
 const vanillaVars = (...varNames) => {
     const id = vanillaClass(``);
     const vars = {};
+    vars.setVars = (vars) => Object.entries(vars)
+        .map(([name, value]) => `--${id}--${name}: ${value || ''};`)
+        .join('\n');
     for (const name of varNames) {
         vars[`var${(0, hanna_utils_1.capitalize)(name)}`] = `--${id}--${name}`;
     }
     return vars;
 };
 exports.vanillaVars = vanillaVars;
+const { varColor, varBg, setVars } = (0, exports.vanillaVars)('color', 'bg');