@reykjavik/webtools 0.1.32 → 0.1.33

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.33
+
+_2024-10-16_
+
+- `@reykjavik/webtools/next/vanillaExtract`:
+  - feat: Deprecate `vanillaNest` and `vanillaClassNested` — in favor of
+    `vanillaClass` with `className` function parameter, or other home-brew
+    solutions.
+  - docs: Improve inline JSDocs and README for the `vanilla*` helpers
+- `@reykjavik/webtools/errorhandling`:
+  - docs: Improve code examples in README
+
 ## 0.1.32
 
 _2024-10-02_

package/README.md

@@ -47,11 +47,9 @@ bun add @reykjavik/webtools
   - [`CookieHubProvider` component](#cookiehubprovider-component)
   - [`useCookieHubConsent`](#usecookiehubconsent)
 - [`@reykjavik/webtools/vanillaExtract`](#reykjavikwebtoolsvanillaextract)
+  - [`vanillaClass`](#vanillaclass)
   - [`vanillaGlobal`](#vanillaglobal)
   - [`vanillaProps`](#vanillaprops)
-  - [`vanillaClass`](#vanillaclass)
-  - [`vanillaClassNested`](#vanillaclassnested)
-  - [`vanillaNest`](#vanillanest)
 - [Framework Specific Tools](#framework-specific-tools)
   - [Remix.run Tools](#remixrun-tools)
   - [Next.js Tools](#nextjs-tools)
@@ -372,7 +370,7 @@ console.log(posts?.reason); // undefined | unknown
 ## `@reykjavik/webtools/errorhandling`
 
 A small set of lightweight tools for handling errors and promises in a safer,
-more structured, FP-style way.
+more structured, FP-ish way.
 
 Errors are always the first return value to promote early, explicit error
 handling.
@@ -386,7 +384,7 @@ 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 a `payload`
+original value is stored in as a `payload` property.
 
 ```ts
 import { asError, type ErrorFromPayload } from '@reykjavik/webtools/errorhandling';
@@ -408,6 +406,7 @@ try {
   console.error(error === someObject); // false
   console.error(error.message === someObject.join(',')); // false
   console.error(error instanceOf ErrorFromPayload); // true
+
   console.error(error.payload === someObject); // true
 }
 ```
@@ -437,7 +436,7 @@ import { type ResultTuple } from '@reykjavik/webtools/errorhandling';
 declare const myResult: ResultTuple<string, Error>;
 
 const [error, result] = myResult;
-// Either `error` or `result` will be `undefined`
+// (One of these two is always `undefined`)
 
 if (error) {
   // Here `error` is an Error instance
@@ -463,7 +462,7 @@ import { type ResultTuple } from '@reykjavik/webtools/errorhandling';
 declare const myResult: ResultTuple<string, Error>;
 
 const [error, result] = myResult;
-// Either `error` or `result` will be `undefined`
+// (One of these two is always `undefined`)
 
 if (error) {
   // Here `error` is an Error instance
@@ -589,7 +588,7 @@ import { Result } from '@reykjavik/webtools/errorhandling';
 try {
   const fooResults = Result.throw(await getFooResultsTuple());
 } catch (fooError) {
-  // error is
+  // Do something with the error from `getFooResultsTuple()`
 }
 ```
 
@@ -765,48 +764,6 @@ local type-safety for access to the full features and expressiveness of real
 CSS.
 ([Background info](https://github.com/vanilla-extract-css/vanilla-extract/discussions/898#discussioncomment-7125457).)
 
-### `vanillaGlobal`
-
-**Syntax:** `vanillaGlobal(css: string): void`
-
-Inserts free-form CSS as a vanilla-extract `globalStyle`.
-
-```ts
-// someFile.css.ts
-import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
-
-vanillaGlobal(`
-  body {
-    background-color: rebeccapurple;
-  }
-`);
-```
-
-### `vanillaProps`
-
-**Syntax:** `vanillaProps(css: string): GlobalStyleRule`
-
-Spreads the return value into a style object, to inject free-form CSS
-properties (or nested blocks)
-
-```ts
-// someFile.css.ts
-import { style } from '@vanilla-extract/css';
-import { vanillaProps } from '@reykjavik/webtools/vanillaExtract';
-
-const myStyle = style({
-  color: 'darksalmon',
-  // ...other style props...
-
-  ...vanillaProps(`
-    /* Plain CSS that's injected into the "myStyle" style block */
-    border-bottom: 1px solid red;
-    color: ${theme.color.primary}; /* I can still use typesafe values */
-    random-css-prop-normally-rejected-by-vanilla-extract: 'YOLO!';
-  `),
-});
-```
-
 ### `vanillaClass`
 
 **Syntax:**
@@ -854,112 +811,57 @@ export const humanReadableClass = vanillaClass(
 );
 ```
 
-### `vanillaClassNested`
-
-**Syntax:** `vanillaClassNested(css: string): string`  
-**Syntax:** `vanillaClassNested(debugId: string, css: string): string`
+### `vanillaGlobal`
 
-Returns a scoped cssClassName styled with free-form CSS.
+**Syntax:** `vanillaGlobal(css: string): void`
 
-It also automatically replaces all `&`-tokens with the selector for the
-auto-generated class-name.
+Inserts free-form CSS as a vanilla-extract `globalStyle`.
 
 ```ts
 // someFile.css.ts
-import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
-
-export const myClass = vanillaClassNested(`
-  background-color: #ccc;
-  padding: .5em 1em;
+import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
 
-  /* Nested blocks begin: */
-  &:hover {
-    background-color: #666;
-    color: white;
-  }
-  & > strong {
-    color: maroon;
-  }
-  html[data-color-theme="unicorn"] & {
-    background-color: pink;
+vanillaGlobal(`
+  body {
+    background-color: rebeccapurple;
   }
 `);
 ```
 
-**NOTE:** All "bare" (un-nested) style properties **must come first**, before
-any nested blocks.
-
-**NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
-anything so fancy. It will also replace `&` characters inside values,
-comments, etc. If you need something more sophisticated, use a custom
-`postcss` config.
-
-### `vanillaNest`
-
-**Syntax:** `vanillaNest(ampSelector: string, css: string): string`
+### `vanillaProps`
 
-Replaces all `&` tokens with the given selector string, in a direct (read.
-"dumb") way. It's mainly useful when used with style-mixins, etc.
+**Syntax:** `vanillaProps(css: string): GlobalStyleRule`
 
-`vanillaNest` does NOT support deeply nested blocks, or anything so fancy. It
-will also replace `&` characters inside values, comments, etc. If you need
-something more sophisticated, use a custom `postcss` config.
+Returns an object that can be safely spread into a vanilla-extract style
+object, to inject free-form CSS properties (or nested blocks).
 
 ```ts
-// someCssHelper.ts
-import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
-
-export const hoverGlow = (
-  ampSelector: string,
-  glowiness?: 'normal' | 'insane'
-) =>
-  vanillaNest(
-    ampSelector,
-    `
-    &:hover {
-      box-shadow: 0 0 20px 5px ${
-        glowiness === 'insane' ? 'hotpink' : 'salmon'
-      };
-    }
-  `
-  );
-
-// ...then, somewhere else in a *.css.ts file:
-
-import { hoverGlow } from '~/someCssHelper.js';
-import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+// someFile.css.ts
+import { style } from '@vanilla-extract/css';
+import { vanillaProps } from '@reykjavik/webtools/vanillaExtract';
 
-vanillaGlobal(`
-  .MyComponent {
-    border: 1px solid #ccc;
-    padding: 1em;
-  }
-  ${hoverGlow('.MyComponent')}
+const myStyle = style({
+  color: 'darksalmon',
+  // ...other style props...
 
-  .MyOtherComponent {
-    border: 1px solid #ccc;
-    padding: 1em;
-  }
-  ${hoverGlow('.MyOtherComponent', 'insane')}
-`);
+  ...vanillaProps(`
+    /* Plain CSS that's injected into the "myStyle" style block */
+    border-bottom: 1px solid red;
+    color: ${theme.color.primary}; /* I can still use typesafe values */
+    random-css-prop-normally-rejected-by-vanilla-extract: 'YOLO!';
+  `),
+});
 ```
 
-(This low-level utility function is used internally by
-[`vanillaClassNested`](#vanillaclassnested).)
-
 ---
 
 ## Framework Specific Tools
 
----
-
 ### Remix.run Tools
 
 See [README-remix.md](./README-remix.md) for helpers and components
 specifically designed for use in Remix.run projects.
 
----
-
 <!-- #fragment anchors to not break older v0.1 @see links -->
 
 <a name="reykjavikwebtoolsnexthttp"></a> <a name="makeerrorizeapphoc"></a>

package/esm/vanillaExtract.d.ts

@@ -20,27 +20,131 @@ export declare const vanillaProps: (css: string) => GlobalStyleRule;
 export declare function vanillaClass(css: string | ((className: string) => string)): string;
 export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export declare const vanillaNest: (ampSelector: string, css: string) => string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Returns a scoped cssClassName styled with free-form CSS.
  *
  * It also automatically replaces all `&`-tokens with
  * the selector for the auto-generated class-name.
  *
- * NOTE: All "bare" (un-nested) style properties must come first,
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
  * before any nested blocks.
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclassnested
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
  */
 export declare function vanillaClassNested(css: string): string;
+/** @deprecated  (Will be removed in v0.2) */
+/**
+ * Returns a scoped cssClassName styled with free-form CSS.
+ *
+ * It also automatically replaces all `&`-tokens with
+ * the selector for the auto-generated class-name.
+ *
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
+ * before any nested blocks.
+ *
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
+ */
 export declare function vanillaClassNested(debugId: string, css: string): string;

package/esm/vanillaExtract.js

@@ -25,15 +25,55 @@ export function vanillaClass(cssOrDebugId, css) {
 }
 // ---------------------------------------------------------------------------
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export const vanillaNest = (ampSelector, css) => css.replace(/&/g, ampSelector);
 export function vanillaClassNested(cssOrDebugId, css) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.32",
+	"version": "0.1.33",
 	"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/vanillaExtract.d.ts

@@ -20,27 +20,131 @@ export declare const vanillaProps: (css: string) => GlobalStyleRule;
 export declare function vanillaClass(css: string | ((className: string) => string)): string;
 export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export declare const vanillaNest: (ampSelector: string, css: string) => string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Returns a scoped cssClassName styled with free-form CSS.
  *
  * It also automatically replaces all `&`-tokens with
  * the selector for the auto-generated class-name.
  *
- * NOTE: All "bare" (un-nested) style properties must come first,
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
  * before any nested blocks.
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclassnested
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
  */
 export declare function vanillaClassNested(css: string): string;
+/** @deprecated  (Will be removed in v0.2) */
+/**
+ * Returns a scoped cssClassName styled with free-form CSS.
+ *
+ * It also automatically replaces all `&`-tokens with
+ * the selector for the auto-generated class-name.
+ *
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
+ * before any nested blocks.
+ *
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
+ */
 export declare function vanillaClassNested(debugId: string, css: string): string;

package/vanillaExtract.js

@@ -31,15 +31,55 @@ function vanillaClass(cssOrDebugId, css) {
 exports.vanillaClass = vanillaClass;
 // ---------------------------------------------------------------------------
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 const vanillaNest = (ampSelector, css) => css.replace(/&/g, ampSelector);
 exports.vanillaNest = vanillaNest;