@reykjavik/webtools 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.12
+
+_2024-02-29_
+
+- feat: Add `@reykjavik/webtools/next/vanillaExtract` component — with
+  plain-CSS injection helpers
+- fix: Mark `peerDependencies` as optional
+
 ## 0.1.11
 
 _2024-02-14_

package/README.md

@@ -33,6 +33,12 @@ bun add @reykjavik/webtools
   - [`SiteImprove` component](#siteimprove-component)
   - [`pingSiteImprove` helper](#pingsiteimprove-helper)
   - [`pingSiteImproveOutbound` helper](#pingsiteimproveoutbound-helper)
+- [`@reykjavik/webtools/vanillaExtract`](#reykjavikwebtoolsvanillaextract)
+  - [`vanillaGlobal`](#vanillaglobal)
+  - [`vanillaProps`](#vanillaprops)
+  - [`vanillaClass`](#vanillaclass)
+  - [`vanillaClassNested`](#vanillaclassnested)
+  - [`vanillaNest`](#vanillanest)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
 
@@ -502,6 +508,170 @@ const handleSubmit = () => {
 
 ---
 
+## `@reykjavik/webtools/vanillaExtract`
+
+Contains helpers for writing [vanilla-extract](https://vanilla-extract.style)
+styles using plain CSS styntax.
+
+This provides an "escape hatch" into regular CSS, when you're willing to trade
+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
+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
+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:** `vanillaClass: (css: string) => string`  
+**Syntax:** `vanillaClass: (debugId: string, css: string) => string`
+
+Returns a scoped cssClassName styled with free-form CSS. This function is a
+thin wrapper around vanilla-extract's `style` function.
+
+```ts
+import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';
+
+export const myClass = vanillaClass(`
+  background-color: #ccc;
+  padding: .5em 1em;
+`);
+
+export const humanReadableClass = vanillaClass(
+  'HumanReadable',
+  `
+    border: 1px dashed hotpink;
+    cursor: pointer;
+  `
+);
+```
+
+### `vanillaClassNested`
+
+**Syntax:** `vanillaClassNested: (css: string) => string`  
+**Syntax:** `vanillaClassNested: (debugId: string, css: string) => string`
+
+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
+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.
+
+### `vanillaNest`
+
+**Syntax:** `vanillaNest: (ampSelector: string, css: string) => string`
+
+Replaces all `&` tokens with the given selector string, in a direct (read.
+"dumb") way. It's mainly useful when used with style-mixins, etc.
+
+This low-level utility function is used internally by
+[`vanillaClassNested`](#vanillaclassnested).
+
+```ts
+import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+
+const hoverGlow = (ampSelector: string, glowiness?: 'normal' | 'insane') =>
+  vanillaNest(
+    ampSelector,
+    `
+    &:hover {
+      box-shadow: 0 0 20px 5px ${
+        glowiness === 'insane' ? 'hotpink' : 'salmon'
+      };
+    }
+  `
+  );
+
+// ...then, somewhere else
+
+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')}
+`);
+```
+
+**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.
+
+---
+
 ## Contributing
 
 This project uses the [Bun runtime](https://bun.sh) for development (tests,
@@ -519,3 +689,7 @@ See
 ```
 
 ```
+
+```
+
+```

package/esm/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./CookieHubConsent.d.tsx" />
 /// <reference path="./next/SiteImprove.d.tsx" />

package/esm/vanillaExtract.d.ts

@@ -0,0 +1,46 @@
+import { GlobalStyleRule } from '@vanilla-extract/css';
+/**
+ * Adds free-form CSS as a globalStyle
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaglobal
+ */
+export declare const vanillaGlobal: (css: string) => void;
+/**
+ * Spreads the return value into a style object, to inject free-form CSS
+ * properties (or nested blocks)
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaprops
+ */
+export declare const vanillaProps: (css: string) => GlobalStyleRule;
+/**
+ * Returns a scoped cssClassName styled with free-form CSS
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaclass
+ */
+export declare function vanillaClass(css: string): string;
+export declare function vanillaClass(debugId: string, css: string): string;
+/**
+ * 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.
+ * If you need something more sophisticated, use a custom `postcss` config.
+ *
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillanest
+ */
+export declare const vanillaNest: (ampSelector: string, css: string) => string;
+/**
+ * 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,
+ * before any nested blocks.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaclassnested
+ */
+export declare function vanillaClassNested(css: string): string;
+export declare function vanillaClassNested(debugId: string, css: string): string;

package/esm/vanillaExtract.js

@@ -0,0 +1,45 @@
+import { globalStyle, style } from '@vanilla-extract/css';
+/**
+ * Adds free-form CSS as a globalStyle
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaglobal
+ */
+export const vanillaGlobal = (css) => globalStyle('x', { x: `} ${css} x{x:` });
+// ---------------------------------------------------------------------------
+/**
+ * Spreads the return value into a style object, to inject free-form CSS
+ * properties (or nested blocks)
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaprops
+ */
+export const vanillaProps = (css) => ({ x: `; ${css}` });
+export function vanillaClass(cssOrDebugId, css) {
+    const debugId = css != null ? cssOrDebugId : undefined;
+    css = css != null ? css : cssOrDebugId;
+    return style(vanillaProps(css), debugId);
+}
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ * If you need something more sophisticated, use a custom `postcss` config.
+ *
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillanest
+ */
+export const vanillaNest = (ampSelector, css) => css.replace(/&/g, ampSelector);
+export function vanillaClassNested(cssOrDebugId, css) {
+    const debugId = css != null ? cssOrDebugId : undefined;
+    css = css != null ? css : cssOrDebugId;
+    const nestPoint = css.indexOf('&');
+    const bareStyles = nestPoint > -1 ? css.slice(0, nestPoint) : css;
+    const nestedStyles = nestPoint > -1 ? css.slice(nestPoint) : undefined;
+    const className = style(vanillaProps(bareStyles), debugId);
+    if (nestedStyles) {
+        vanillaGlobal(vanillaNest(`.${className}`, nestedStyles));
+    }
+    return className;
+}

package/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./vanillaExtract.d.ts" />
 /// <reference path="./http.d.ts" />
 /// <reference path="./CookieHubConsent.d.tsx" />
 /// <reference path="./next/SiteImprove.d.tsx" />

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.11",
+	"version": "0.1.12",
 	"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",
@@ -14,10 +14,25 @@
 		"@reykjavik/hanna-utils": "^0.2.3"
 	},
 	"peerDependencies": {
+		"@vanilla-extract/css": "^1.14.1",
 		"next": ">=11",
 		"react": ">=16.8.0",
 		"react-dom": ">=16.8.0"
 	},
+	"peerDependenciesMeta": {
+		"@vanilla-extract/css": {
+			"optional": true
+		},
+		"next": {
+			"optional": true
+		},
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
 	"engines": {
 		"node": ">=16"
 	},
@@ -27,6 +42,10 @@
 			"import": "./esm/index.js",
 			"require": "./index.js"
 		},
+		"./vanillaExtract": {
+			"import": "./esm/vanillaExtract.js",
+			"require": "./vanillaExtract.js"
+		},
 		"./http": {
 			"import": "./esm/http.js",
 			"require": "./http.js"

package/vanillaExtract.d.ts

@@ -0,0 +1,46 @@
+import { GlobalStyleRule } from '@vanilla-extract/css';
+/**
+ * Adds free-form CSS as a globalStyle
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaglobal
+ */
+export declare const vanillaGlobal: (css: string) => void;
+/**
+ * Spreads the return value into a style object, to inject free-form CSS
+ * properties (or nested blocks)
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaprops
+ */
+export declare const vanillaProps: (css: string) => GlobalStyleRule;
+/**
+ * Returns a scoped cssClassName styled with free-form CSS
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaclass
+ */
+export declare function vanillaClass(css: string): string;
+export declare function vanillaClass(debugId: string, css: string): string;
+/**
+ * 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.
+ * If you need something more sophisticated, use a custom `postcss` config.
+ *
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillanest
+ */
+export declare const vanillaNest: (ampSelector: string, css: string) => string;
+/**
+ * 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,
+ * before any nested blocks.
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaclassnested
+ */
+export declare function vanillaClassNested(css: string): string;
+export declare function vanillaClassNested(debugId: string, css: string): string;

package/vanillaExtract.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vanillaClassNested = exports.vanillaNest = exports.vanillaClass = exports.vanillaProps = exports.vanillaGlobal = void 0;
+const css_1 = require("@vanilla-extract/css");
+/**
+ * Adds free-form CSS as a globalStyle
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaglobal
+ */
+const vanillaGlobal = (css) => (0, css_1.globalStyle)('x', { x: `} ${css} x{x:` });
+exports.vanillaGlobal = vanillaGlobal;
+// ---------------------------------------------------------------------------
+/**
+ * Spreads the return value into a style object, to inject free-form CSS
+ * properties (or nested blocks)
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillaprops
+ */
+const vanillaProps = (css) => ({ x: `; ${css}` });
+exports.vanillaProps = vanillaProps;
+function vanillaClass(cssOrDebugId, css) {
+    const debugId = css != null ? cssOrDebugId : undefined;
+    css = css != null ? css : cssOrDebugId;
+    return (0, css_1.style)((0, exports.vanillaProps)(css), debugId);
+}
+exports.vanillaClass = vanillaClass;
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ * If you need something more sophisticated, use a custom `postcss` config.
+ *
+ *
+ * @see https://github.com/reykjavikcity/webtools/tree/v0.1#vanillanest
+ */
+const vanillaNest = (ampSelector, css) => css.replace(/&/g, ampSelector);
+exports.vanillaNest = vanillaNest;
+function vanillaClassNested(cssOrDebugId, css) {
+    const debugId = css != null ? cssOrDebugId : undefined;
+    css = css != null ? css : cssOrDebugId;
+    const nestPoint = css.indexOf('&');
+    const bareStyles = nestPoint > -1 ? css.slice(0, nestPoint) : css;
+    const nestedStyles = nestPoint > -1 ? css.slice(nestPoint) : undefined;
+    const className = (0, css_1.style)((0, exports.vanillaProps)(bareStyles), debugId);
+    if (nestedStyles) {
+        (0, exports.vanillaGlobal)((0, exports.vanillaNest)(`.${className}`, nestedStyles));
+    }
+    return className;
+}
+exports.vanillaClassNested = vanillaClassNested;