@reykjavik/webtools 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.2.7
+
+_2025-09-01_
+
+- `@reykjavik/webtools/fixIcelandicLocale`:
+  - fix: Check for support of each Intl class separately
+- docs: Improve JSDocs and README for `asError()` and `ErrorFromPayload`
+
+## 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_

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)
@@ -385,7 +386,8 @@ Guarantees that a caught (`catch (e)`) value of `unknown` type, is indeed an
 
 If the input is an `Error` instance, it is returned as-is. If the input is
 something else it is wrapped in a new `ErrorFromPayload` instance, and the
-original value is stored in as a `payload` property.
+original value is stored in as a `payload` property, and it's `.toString()` is
+used for the `message` property.
 
 ```ts
 import { asError, type ErrorFromPayload } from '@reykjavik/webtools/errorhandling';
@@ -394,21 +396,23 @@ const theError = new Error('Something went wrong');
 try {
   throw theError;
 } catch (err) {
+  // theError is an instance of Error so it's returned as-is
   const error = asError(theError);
   console.error(error === theError); // true
-  console.error('patload' in error); // false
+  console.error('payload' in error); // false
 }
 
-const someObject = ['Something went wrong'];
+const someObject = ['Oops', 'Something went wrong'];
 try {
   throw someObject;
 } catch (err) {
+  // the thrown someObject is not an Error so an `ErrorFromPayload` is returned
   const error = asError(someObject);
   console.error(error === someObject); // false
-  console.error(error.message === someObject.join(',')); // false
   console.error(error instanceOf ErrorFromPayload); // true
 
   console.error(error.payload === someObject); // true
+  console.error(error.message === someObject.join(',')); // true
 }
 ```
 
@@ -821,14 +825,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 +852,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 +899,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 +984,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 +1044,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/errorhandling.d.ts

@@ -1,10 +1,18 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */
 export declare class ErrorFromPayload extends Error {
+    /**
+     * This payload property is only set if the original `throw` value was NOT
+     * `instanceof Error`.
+     *
+     * In such cases it contains the thrown value as is, and the `message`
+     * property of this `ErrorFromPayload` instance is set to the `.toString()`
+     * representation of the payload.
+     */
     payload?: unknown;
     constructor(payload: unknown);
     name: string;
@@ -50,7 +58,7 @@ export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | Fail
  * `[error, results]` tuple with the `result` and `error` also attached as
  * named properties.
  *
- * Works on both promises and sync callback functions.
+ * Works on both promises and (synchronous) callback functions.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#resultcatch
  */

package/errorhandling.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Result = exports.asError = exports.ErrorFromPayload = void 0;
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */

package/esm/errorhandling.d.ts

@@ -1,10 +1,18 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */
 export declare class ErrorFromPayload extends Error {
+    /**
+     * This payload property is only set if the original `throw` value was NOT
+     * `instanceof Error`.
+     *
+     * In such cases it contains the thrown value as is, and the `message`
+     * property of this `ErrorFromPayload` instance is set to the `.toString()`
+     * representation of the payload.
+     */
     payload?: unknown;
     constructor(payload: unknown);
     name: string;
@@ -50,7 +58,7 @@ export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | Fail
  * `[error, results]` tuple with the `result` and `error` also attached as
  * named properties.
  *
- * Works on both promises and sync callback functions.
+ * Works on both promises and (synchronous) callback functions.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#resultcatch
  */

package/esm/errorhandling.js

@@ -1,6 +1,6 @@
 /**
- * Error subclass for thrown values that got cought and turned into an actual
- * Error, with the thrown value as the `payload` property.
+ * Error subclass for thrown NON-Error values that got turned into an actual
+ * Error, with the original thrown value as the `payload` property.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.2/README.md#aserror
  */

package/esm/fixIcelandicLocale.js

@@ -7,8 +7,12 @@ import { _PatchedCollator, _PatchedDateTimeFormat, _patchedDateToLocaleDateStrin
 if (!Intl.Collator.supportedLocalesOf(['is']).length) {
     Intl.Collator = _PatchedCollator;
     String.prototype.localeCompare = _patchedStringLocaleCompare;
+}
+if (!Intl.NumberFormat.supportedLocalesOf(['is']).length) {
     Intl.NumberFormat = _PatchedNumberFormat;
     Number.prototype.toLocaleString = _patchedNumberToLocaleString;
+}
+if (!Intl.DateTimeFormat.supportedLocalesOf(['is']).length) {
     Intl.DateTimeFormat = _PatchedDateTimeFormat;
     Date.prototype.toLocaleString = _patchedDateToLocaleString;
     Date.prototype.toLocaleDateString = _patchedDateToLocaleDateString;

package/esm/http.d.ts

@@ -11,6 +11,7 @@ export declare const HTTP_103_EarlyHints = 103;
 export declare const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export declare const HTTP_201_Created = 201;
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export declare const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export declare const HTTP_203_NonAuthoritativeInformation = 203;

package/esm/http.js

@@ -12,7 +12,7 @@ export const HTTP_103_EarlyHints = 103;
 export const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export const HTTP_201_Created = 201;
-/* The request has been received but not yet acted upon. Another process or server handles the request. */
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export const HTTP_203_NonAuthoritativeInformation = 203;

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/fixIcelandicLocale.js

@@ -9,8 +9,12 @@ const fixIcelandicLocale_privates_js_1 = require("./fixIcelandicLocale.privates.
 if (!Intl.Collator.supportedLocalesOf(['is']).length) {
     Intl.Collator = fixIcelandicLocale_privates_js_1._PatchedCollator;
     String.prototype.localeCompare = fixIcelandicLocale_privates_js_1._patchedStringLocaleCompare;
+}
+if (!Intl.NumberFormat.supportedLocalesOf(['is']).length) {
     Intl.NumberFormat = fixIcelandicLocale_privates_js_1._PatchedNumberFormat;
     Number.prototype.toLocaleString = fixIcelandicLocale_privates_js_1._patchedNumberToLocaleString;
+}
+if (!Intl.DateTimeFormat.supportedLocalesOf(['is']).length) {
     Intl.DateTimeFormat = fixIcelandicLocale_privates_js_1._PatchedDateTimeFormat;
     Date.prototype.toLocaleString = fixIcelandicLocale_privates_js_1._patchedDateToLocaleString;
     Date.prototype.toLocaleDateString = fixIcelandicLocale_privates_js_1._patchedDateToLocaleDateString;

package/http.d.ts

@@ -11,6 +11,7 @@ export declare const HTTP_103_EarlyHints = 103;
 export declare const HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 export declare const HTTP_201_Created = 201;
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 export declare const HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 export declare const HTTP_203_NonAuthoritativeInformation = 203;

package/http.js

@@ -16,7 +16,7 @@ exports.HTTP_103_EarlyHints = 103;
 exports.HTTP_200_OK = 200;
 /** The request succeeded, and a new resource was created as a result. This is typically the response sent after POST or PUT requests. */
 exports.HTTP_201_Created = 201;
-/* The request has been received but not yet acted upon. Another process or server handles the request. */
+/** The request has been received but not yet acted upon. Another process or server handles the request. */
 exports.HTTP_202_Accepted = 202;
 /** The returned metadata is not necessarily complete. */
 exports.HTTP_203_NonAuthoritativeInformation = 203;

package/package.json

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