@reykjavik/webtools 0.1.33 → 0.1.35

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.1.35
+
+_2024-10-18_
+
+- `@reykjavik/webtools/next/vanillaExtract`:
+  - feat: `vanillaClass` auto-replaces `.&` tokens in a plain-string input
+  - docs: Minor improvements to README and JSDoc comments
+
+## 0.1.34
+
+_2024-10-17_
+
+- `@reykjavik/webtools/next/vanillaExtract`:
+  - feat: `vanillaClass` passes `classNameSelector` a second parameter to the
+    render callback.
+
 ## 0.1.33
 
 _2024-10-16_

package/README.md

@@ -767,41 +767,62 @@ CSS.
 ### `vanillaClass`
 
 **Syntax:**
-`vanillaClass(css: string | ((className: string) => string)): string`  
+`vanillaClass(css: string | ((className: string, classNameSelector: string) => string)): string`  
 **Syntax:**
-`vanillaClass(debugId: string, css: string | ((className: string) => string)): string`
+`vanillaClass(debugId: string, css: string | ((className: string, classNameSelector: string) => string)): string`
 
 Returns a scoped cssClassName styled with free-form CSS. This function is a
 thin wrapper around vanilla-extract's `style` function.
 
+When you pass it a string, all `.&` tokens are automatically replaced with the
+selector for the auto-generated class-name. Note that in such cases EVERY
+style property must be wrapped in a selector block.
+
+To opt out of the `.&` replacement, use the callback function signature.
+
 ```ts
 // someFile.css.ts
 import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';
 
+// Simple class selector block
 export const myClass = vanillaClass(`
   background-color: #ccc;
   padding: .5em 1em;
 `);
 
-// Passing a function to get the generated class name for
+// With .& tokens that get replaced with the generated class-name
+export const myClasWithAmp = vanillaClass(`
+  .& {
+    background-color: #ccc;
+    padding: .5em 1em;
+  }
+  .& > strong {
+    color: #c00;
+  }
+`);
+
+// Passing a function to get the generated class-name for
 // more complex styles.
 export const myOtherClass = vanillaClass(
-  (className) => `
-    .${className} { 
+  (classNameRaw, classNameSelector) => `
+    ${classNameSelector} { 
       background-color: #ccc;
       padding: .5em 1em;
     }
-    .${className} > strong {
+    [class="${classNameRaw}"] > strong {
       color: #c00;
     }
     @media (min-width: 800px) {
-      .${className} {
+      ${classNameSelector} {
         background-color: #eee;
       }
     }
+    /* ".&" tokens in CSS returned from a callback are not replaced */
+    .& { will-not-be: interpolated; }
   `
 );
 
+// With a human readable debugId
 export const humanReadableClass = vanillaClass(
   'HumanReadable',
   `
@@ -811,6 +832,9 @@ export const humanReadableClass = vanillaClass(
 );
 ```
 
+(NOTE: The dot-prefixed `.&` pattern is chosen to not conflict with the bare
+`&` token in modern nested CSS.)
+
 ### `vanillaGlobal`
 
 **Syntax:** `vanillaGlobal(css: string): void`

package/esm/next/http.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="node" resolution-mode="require"/>
 import React, { FunctionComponent } from 'react';
 import type { Cleanup } from '@reykjavik/hanna-utils';
-import type { ServerResponse } from 'http';
 import type { AppType } from 'next/app.js';
+import type { ServerResponse } from 'node:http';
 import type { HTTP_ERROR_ALL, TTLConfig } from '../http.js';
 export * from '../http.js';
 type NextContextLike = {

package/esm/vanillaExtract.d.ts

@@ -12,13 +12,25 @@ export declare const vanillaGlobal: (css: string) => void;
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaprops
  */
 export declare const vanillaProps: (css: string) => GlobalStyleRule;
+type ClassNameCallback = (
+/** The raw standalone class-name. (i.e. `"Component_b6ff51c"`) */
+classNameRaw: string, 
+/** The class-name prefixed with a "." for convenence (i.e. `".Component_b6ff51c"`) */
+classNameSelector: string) => string;
 /**
- * Returns a scoped cssClassName styled with free-form CSS
+ * Returns a scoped cssClassName styled with free-form CSS. This function is a
+ * thin wrapper around vanilla-extract's `style` function.
+ *
+ * When you pass it a string, all `.&` tokens are automatically replaced with the
+ * selector for the auto-generated class-name. Note that in such cases EVERY
+ * style property must be wrapped in a selector block.
+ *
+ * To opt out of the `.&` replacement, use the callback function signature.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclass
  */
-export declare function vanillaClass(css: string | ((className: string) => string)): string;
-export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
+export declare function vanillaClass(css: string | ClassNameCallback): string;
+export declare function vanillaClass(debugId: string, css: string | ClassNameCallback): string;
 /**
  * @deprecated  (Will be removed in v0.2)
  *
@@ -148,3 +160,4 @@ export declare function vanillaClassNested(css: string): string;
  * `postcss` config.
  */
 export declare function vanillaClassNested(debugId: string, css: string): string;
+export {};

package/esm/vanillaExtract.js

@@ -16,12 +16,14 @@ export const vanillaProps = (css) => ({ x: `; ${css}` });
 export function vanillaClass(cssOrDebugId, css) {
     const debugId = css != null ? cssOrDebugId : undefined;
     css = css != null ? css : cssOrDebugId;
-    if (typeof css === 'function') {
-        const className = style({}, debugId);
-        vanillaGlobal(css(className));
-        return className;
+    if (typeof css === 'string' && !/.&/.test(css)) {
+        return style(vanillaProps(css), debugId);
     }
-    return style(vanillaProps(css), debugId);
+    const className = style({}, debugId);
+    vanillaGlobal(typeof css === 'function'
+        ? css('className', `.${className}`)
+        : css.replace(/.&/g, `.${className}`));
+    return className;
 }
 // ---------------------------------------------------------------------------
 /**

package/next/http.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="node" />
 import React, { FunctionComponent } from 'react';
 import type { Cleanup } from '@reykjavik/hanna-utils';
-import type { ServerResponse } from 'http';
 import type { AppType } from 'next/app.js';
+import type { ServerResponse } from 'node:http';
 import type { HTTP_ERROR_ALL, TTLConfig } from '../http.js';
 export * from '../http.js';
 type NextContextLike = {

package/package.json

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

@@ -12,13 +12,25 @@ export declare const vanillaGlobal: (css: string) => void;
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaprops
  */
 export declare const vanillaProps: (css: string) => GlobalStyleRule;
+type ClassNameCallback = (
+/** The raw standalone class-name. (i.e. `"Component_b6ff51c"`) */
+classNameRaw: string, 
+/** The class-name prefixed with a "." for convenence (i.e. `".Component_b6ff51c"`) */
+classNameSelector: string) => string;
 /**
- * Returns a scoped cssClassName styled with free-form CSS
+ * Returns a scoped cssClassName styled with free-form CSS. This function is a
+ * thin wrapper around vanilla-extract's `style` function.
+ *
+ * When you pass it a string, all `.&` tokens are automatically replaced with the
+ * selector for the auto-generated class-name. Note that in such cases EVERY
+ * style property must be wrapped in a selector block.
+ *
+ * To opt out of the `.&` replacement, use the callback function signature.
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclass
  */
-export declare function vanillaClass(css: string | ((className: string) => string)): string;
-export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
+export declare function vanillaClass(css: string | ClassNameCallback): string;
+export declare function vanillaClass(debugId: string, css: string | ClassNameCallback): string;
 /**
  * @deprecated  (Will be removed in v0.2)
  *
@@ -148,3 +160,4 @@ export declare function vanillaClassNested(css: string): string;
  * `postcss` config.
  */
 export declare function vanillaClassNested(debugId: string, css: string): string;
+export {};

package/vanillaExtract.js

@@ -21,12 +21,14 @@ exports.vanillaProps = vanillaProps;
 function vanillaClass(cssOrDebugId, css) {
     const debugId = css != null ? cssOrDebugId : undefined;
     css = css != null ? css : cssOrDebugId;
-    if (typeof css === 'function') {
-        const className = (0, css_1.style)({}, debugId);
-        (0, exports.vanillaGlobal)(css(className));
-        return className;
+    if (typeof css === 'string' && !/.&/.test(css)) {
+        return (0, css_1.style)((0, exports.vanillaProps)(css), debugId);
     }
-    return (0, css_1.style)((0, exports.vanillaProps)(css), debugId);
+    const className = (0, css_1.style)({}, debugId);
+    (0, exports.vanillaGlobal)(typeof css === 'function'
+        ? css('className', `.${className}`)
+        : css.replace(/.&/g, `.${className}`));
+    return className;
 }
 exports.vanillaClass = vanillaClass;
 // ---------------------------------------------------------------------------