@reykjavik/webtools 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.2.6
+
+_2025-06-20_
+
+- `@reykjavik/webtools/next/vanillaExtract`:
+  - feat: Add `vanillaVars` helper to generate privately scoped CSS variables
+
+## 0.2.5
+
+_2025-05-21_
+
+- `@reykjavik/webtools/async`:
+  - feat: Support passing `AbortSignal` to `sleep` and `addLag` helpers
+
 ## 0.2.4
 
 _2025-05-09_
@@ -39,7 +53,7 @@ _2024-12-17_
 _2024-12-12_
 
 - feat: Add `@reykjavik/webtools/react-router/*` (previously `/remix/*`)
-- **BREAKING** feat: Remove all `@reykjavik/webtools/react-router/*` modules
+- **BREAKING** feat: Remove all `@reykjavik/webtools/remix/*` modules
 - **BREAKING** feat: Bump `pkg.engines.node` version to >=20
 - **BREAKING** feat: Remove `@reykjavik/webtools/next/SiteImprove` (deprecated
   module)

package/README.md

@@ -51,6 +51,7 @@ bun add @reykjavik/webtools
   - [`vanillaClass`](#vanillaclass)
   - [`vanillaGlobal`](#vanillaglobal)
   - [`vanillaProps`](#vanillaprops)
+  - [`vanillaVars`](#vanillavars)
 - [Framework Specific Tools](#framework-specific-tools)
   - [React-Router Tools](#react-router-tools)
   - [Next.js Tools](#nextjs-tools)
@@ -821,14 +822,26 @@ To opt out of the `&&` replacement, use the callback function signature.
 // someFile.css.ts
 import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';
 
-// Simple class selector block
+// 1) Simple class selector block — no sub-selectors — auto-wrapped
+// in a class-name selector block.
 export const myClass = vanillaClass(`
   background-color: #ccc;
   padding: .5em 1em;
 `);
+// Generated CSS:
+/*
+  .x1y2z3 {
+    background-color: #ccc;
+    padding: .5em 1em;
+  }
+*/
+
+// ---------------------------------------------------------------------------
 
-// With && tokens that get replaced with the generated class-name
-export const myClasWithAmp = vanillaClass(`
+// 2) More advanced usage with `&&` tokens that get replaced with the
+// generated class-name selector (prefixed with a dot).
+export const myClasWithAmp = vanillaClass(
+  `
   && {
     background-color: #ccc;
     padding: .5em 1em;
@@ -836,10 +849,38 @@ export const myClasWithAmp = vanillaClass(`
   && > strong {
     color: #c00;
   }
-`);
+  @media (min-width: 800px) {
+    && {
+      background-color: #eee;
+    }
+  }
+  /* NOTE: Root-level CSS rules are NOT auto-wrapped when ` &&
+    ` tokens are otherwise present */
+  color: blue;
+`
+);
+// Generated CSS:
+/*
+  .y2X1z3 {
+    background-color: #ccc;
+    padding: .5em 1em;
+  }
+  .y2X1z3 > strong {
+    color: #c00;
+  }
+  @media (min-width: 800px) {
+    .y2X1z3 {
+      background-color: #eee;
+    }
+  }
+  /* NOTE: Root-level CSS rules are NOT auto-wrapped when `&&` tokens are otherwise present *​/
+  color: blue;
+*/
 
-// Passing a function to get the generated class-name for
-// more complex styles.
+// ---------------------------------------------------------------------------
+
+// 3) Advanced use: Pass a function to get the raw generated class-name,
+// plus a more convenient dot-prefixed selector for the class-name.
 export const myOtherClass = vanillaClass(
   (classNameRaw, classNameSelector) => `
     ${classNameSelector} { 
@@ -855,22 +896,48 @@ export const myOtherClass = vanillaClass(
       }
     }
     /* NOTE: '&&' tokens returned from a callback function are NOT replaced */
-    && { will-not-be: interpolated; }
+    && { this-is-not: interpolated; }
   `
 );
+// Generated CSS:
+/* 
+  .y3z1X2 {
+    background-color: #ccc;
+    padding: .5em 1em;
+  }
+  [class="y3z1X2"] > strong {
+    color: #c00;
+  }
+  @media (min-width: 800px) {
+    .y3z1X2 {
+      background-color: #eee;
+    }
+  }
+  /* NOTE: '&&' tokens returned from a callback function are NOT replaced *​​/
+  && { this-is-not: interpolated; }
+*/
+
+// ---------------------------------------------------------------------------
 
-// With a human readable debugId
+// 4) ...with a human readable debugId
 export const humanReadableClass = vanillaClass(
-  'HumanReadable',
+  'HumanReadable__classNamePrefix',
   `
     border: 1px dashed hotpink;
     cursor: pointer;
   `
 );
+// Generated CSS:
+/*
+  .HumanReadable__classNamePrefix_x2y1z3 {
+    border: 1px dashed hotpink;
+    cursor: pointer;
+  }
+*/
 ```
 
-(NOTE: The dot-prefixed `&&` pattern is chosen to not conflict with the bare
-`&` token in modern nested CSS.)
+(NOTE: The dot-prefixed `&&` pattern was chosen as to not conflict with the
+bare `&` token in modern nested CSS.)
 
 ### `vanillaGlobal`
 
@@ -914,6 +981,59 @@ const myStyle = style({
 });
 ```
 
+### `vanillaVars`
+
+**Syntax:**
+`` vanillaVars(...varNames: Array<T>): Record <`var${Capitalize<T>}`, string> ``
+
+Returns an object with privately scoped CSS variables props. Pass them around
+and use them in your CSS.
+
+```ts
+// MyComponent.css.ts
+import {
+  vanillaVars,
+  vanillaGlobal,
+} from '@reykjavik/webtools/vanillaExtract';
+
+export const { varPrimaryColor, varSecondaryColor } = vanillaVars(
+  'primaryColor',
+  'secondaryColor'
+);
+
+vanillaGlobal(`
+  :root {
+    ${varPrimaryColor}: #ff0000;
+    ${varSecondaryColor}: #00ff00;
+  }
+  body {
+    background-color: var(${varPrimaryColor});
+    color: var(${varSecondaryColor});
+  }
+`);
+```
+
+…and then in your component:
+
+```ts
+// MyComponent.tsx
+import React from 'react';
+import * as cl from './someFile.css.ts';
+
+export function MyComponent() {
+  return (
+    <div
+      style={{
+        [cl.varPrimaryColor]: 'yellow',
+        [cl.varSecondaryColor]: 'blue',
+      }}
+    >
+      ...children...
+    </div>
+  );
+}
+```
+
 ---
 
 ## Framework Specific Tools
@@ -921,7 +1041,7 @@ const myStyle = style({
 ### React-Router Tools
 
 See [README-rr.md](./README-rr.md) for helpers and components specifically
-designed for use in Remix.run projects.
+designed for use in React-router projects.
 
 (NOTE: If you're still using [Remix.run](https://remix.run) you can install
 version `"^0.1.22"` of this package.)

package/async.d.ts

@@ -4,12 +4,16 @@ type PlainObj = Record<string, unknown>;
  * Simple sleep function. Returns a promise that resolves after `length`
  * milliseconds.
  */
-export declare const sleep: (length: number) => Promise<void>;
+export declare const sleep: (length: number, opts?: {
+    signal?: AbortSignal;
+}) => Promise<void>;
 /**
  * Returns a function that adds lag/delay to a promise chain,
  * passing the promise payload through.
  */
-export declare const addLag: (length: number) => <T>(res: T) => Promise<T>;
+export declare const addLag: (length: number, opts?: {
+    signal?: AbortSignal;
+}) => <T>(res: T) => Promise<T>;
 /**
  * Resolves as soon as all of the passed `promises` have resolved/settled,
  * or after `timeout` milliseconds — whichever comes first.

package/async.js

@@ -7,14 +7,33 @@ exports.maxWait = maxWait;
  * milliseconds.
  */
 /*#__NO_SIDE_EFFECTS__*/
-const sleep = (length) => new Promise((resolve) => setTimeout(resolve, length));
+const sleep = (length, opts) => new Promise((resolve, reject) => {
+    const signal = opts && opts.signal;
+    if (!signal) {
+        return setTimeout(resolve, length);
+    }
+    if (signal.aborted) {
+        return reject(signal.reason);
+    }
+    const onAbort = () => {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+        reject(signal.reason);
+    };
+    signal.addEventListener('abort', onAbort);
+    const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+    }, length);
+});
 exports.sleep = sleep;
 /**
  * Returns a function that adds lag/delay to a promise chain,
  * passing the promise payload through.
  */
 /*#__NO_SIDE_EFFECTS__*/
-const addLag = (length) => (res) => (0, exports.sleep)(length).then(() => res);
+const addLag = (length, opts) => (res) => (0, exports.sleep)(length, opts).then(() => res);
 exports.addLag = addLag;
 /*#__NO_SIDE_EFFECTS__*/
 function maxWait(timeout, promises) {

package/esm/async.d.ts

@@ -4,12 +4,16 @@ type PlainObj = Record<string, unknown>;
  * Simple sleep function. Returns a promise that resolves after `length`
  * milliseconds.
  */
-export declare const sleep: (length: number) => Promise<void>;
+export declare const sleep: (length: number, opts?: {
+    signal?: AbortSignal;
+}) => Promise<void>;
 /**
  * Returns a function that adds lag/delay to a promise chain,
  * passing the promise payload through.
  */
-export declare const addLag: (length: number) => <T>(res: T) => Promise<T>;
+export declare const addLag: (length: number, opts?: {
+    signal?: AbortSignal;
+}) => <T>(res: T) => Promise<T>;
 /**
  * Resolves as soon as all of the passed `promises` have resolved/settled,
  * or after `timeout` milliseconds — whichever comes first.

package/esm/async.js

@@ -3,13 +3,32 @@
  * milliseconds.
  */
 /*#__NO_SIDE_EFFECTS__*/
-export const sleep = (length) => new Promise((resolve) => setTimeout(resolve, length));
+export const sleep = (length, opts) => new Promise((resolve, reject) => {
+    const signal = opts && opts.signal;
+    if (!signal) {
+        return setTimeout(resolve, length);
+    }
+    if (signal.aborted) {
+        return reject(signal.reason);
+    }
+    const onAbort = () => {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+        reject(signal.reason);
+    };
+    signal.addEventListener('abort', onAbort);
+    const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+    }, length);
+});
 /**
  * Returns a function that adds lag/delay to a promise chain,
  * passing the promise payload through.
  */
 /*#__NO_SIDE_EFFECTS__*/
-export const addLag = (length) => (res) => sleep(length).then(() => res);
+export const addLag = (length, opts) => (res) => sleep(length, opts).then(() => res);
 /*#__NO_SIDE_EFFECTS__*/
 export function maxWait(timeout, promises) {
     if (Array.isArray(promises)) {

package/esm/react-router/Wait.d.ts

@@ -27,7 +27,7 @@ type WaitFallbacks = {
 };
 export type WaitProps<T> = WaitPropsBase<T> & WaitFallbacks;
 /**
- * A function component that wraps `@reykjavik/webtools/remix/Wait` to provide
+ * A function component that wraps `@reykjavik/webtools/react-router/Wait` to provide
  * custom properties for `meanwhile` and `error` fallbacks, and/or other
  * behaviors.
  *
@@ -37,7 +37,7 @@ export type WaitComponent<CustomProps extends Record<string, unknown> = Record<n
     displayName?: string;
 };
 /**
- * A thin wrapper around [Remix's `Await`](https://remix.run/docs/en/2/components/await)
+ * A thin wrapper around [React-router's `Await`](https://reactrouter.com/api/components/Await)
  * component, to provide a more ergonomic API.
  *
  * If the awaited promise (`props.for`) resolves to an object with a truthy

package/esm/react-router/Wait.js

@@ -1,7 +1,7 @@
 import React, { Suspense } from 'react';
 import { Await } from 'react-router';
 /**
- * A thin wrapper around [Remix's `Await`](https://remix.run/docs/en/2/components/await)
+ * A thin wrapper around [React-router's `Await`](https://reactrouter.com/api/components/Await)
  * component, to provide a more ergonomic API.
  *
  * If the awaited promise (`props.for`) resolves to an object with a truthy

package/esm/vanillaExtract.d.ts

@@ -31,4 +31,11 @@ classNameSelector: string) => string;
  */
 export declare function vanillaClass(css: string | ClassNameCallback): string;
 export declare function vanillaClass(debugId: string, css: string | ClassNameCallback): string;
+/**
+ * Returns an object with privately scoped CSS variables props.
+ * Pass them around and use them in your CSS.
+ *
+ * @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 {};

package/esm/vanillaExtract.js

@@ -1,3 +1,4 @@
+import { capitalize } from '@reykjavik/hanna-utils';
 import { globalStyle, style } from '@vanilla-extract/css';
 /**
  * Adds free-form CSS as a globalStyle
@@ -25,3 +26,18 @@ export function vanillaClass(cssOrDebugId, css) {
         : css.replace(/&&/g, `.${className}`));
     return className;
 }
+// ---------------------------------------------------------------------------
+/**
+ * Returns an object with privately scoped CSS variables props.
+ * Pass them around and use them in your CSS.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#vanillacvars
+ */
+export const vanillaVars = (...varNames) => {
+    const id = vanillaClass(``);
+    const vars = {};
+    for (const name of varNames) {
+        vars[`var${capitalize(name)}`] = `--${id}--${name}`;
+    }
+    return vars;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"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",

package/react-router/Wait.d.ts

@@ -27,7 +27,7 @@ type WaitFallbacks = {
 };
 export type WaitProps<T> = WaitPropsBase<T> & WaitFallbacks;
 /**
- * A function component that wraps `@reykjavik/webtools/remix/Wait` to provide
+ * A function component that wraps `@reykjavik/webtools/react-router/Wait` to provide
  * custom properties for `meanwhile` and `error` fallbacks, and/or other
  * behaviors.
  *
@@ -37,7 +37,7 @@ export type WaitComponent<CustomProps extends Record<string, unknown> = Record<n
     displayName?: string;
 };
 /**
- * A thin wrapper around [Remix's `Await`](https://remix.run/docs/en/2/components/await)
+ * A thin wrapper around [React-router's `Await`](https://reactrouter.com/api/components/Await)
  * component, to provide a more ergonomic API.
  *
  * If the awaited promise (`props.for`) resolves to an object with a truthy

package/react-router/Wait.js

@@ -37,7 +37,7 @@ exports.Wait = void 0;
 const react_1 = __importStar(require("react"));
 const react_router_1 = require("react-router");
 /**
- * A thin wrapper around [Remix's `Await`](https://remix.run/docs/en/2/components/await)
+ * A thin wrapper around [React-router's `Await`](https://reactrouter.com/api/components/Await)
  * component, to provide a more ergonomic API.
  *
  * If the awaited promise (`props.for`) resolves to an object with a truthy

package/vanillaExtract.d.ts

@@ -31,4 +31,11 @@ classNameSelector: string) => string;
  */
 export declare function vanillaClass(css: string | ClassNameCallback): string;
 export declare function vanillaClass(debugId: string, css: string | ClassNameCallback): string;
+/**
+ * Returns an object with privately scoped CSS variables props.
+ * Pass them around and use them in your CSS.
+ *
+ * @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 {};

package/vanillaExtract.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.vanillaProps = exports.vanillaGlobal = void 0;
+exports.vanillaVars = exports.vanillaProps = exports.vanillaGlobal = void 0;
 exports.vanillaClass = vanillaClass;
+const hanna_utils_1 = require("@reykjavik/hanna-utils");
 const css_1 = require("@vanilla-extract/css");
 /**
  * Adds free-form CSS as a globalStyle
@@ -31,3 +32,19 @@ function vanillaClass(cssOrDebugId, css) {
         : css.replace(/&&/g, `.${className}`));
     return className;
 }
+// ---------------------------------------------------------------------------
+/**
+ * Returns an object with privately scoped CSS variables props.
+ * Pass them around and use them in your CSS.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#vanillacvars
+ */
+const vanillaVars = (...varNames) => {
+    const id = vanillaClass(``);
+    const vars = {};
+    for (const name of varNames) {
+        vars[`var${(0, hanna_utils_1.capitalize)(name)}`] = `--${id}--${name}`;
+    }
+    return vars;
+};
+exports.vanillaVars = vanillaVars;