@reykjavik/webtools 0.1.34 → 0.1.35

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 - ... <!-- 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_

package/README.md

@@ -774,24 +774,42 @@ 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.
+
 ```ts
 // someFile.css.ts
 import { vanillaClass } from '@reykjavik/webtools/vanillaExtract';
 
+// Simple class selector block
 export const myClass = vanillaClass(`
   background-color: #ccc;
   padding: .5em 1em;
 `);
 
+// 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, classNameSelector) => `
+  (classNameRaw, classNameSelector) => `
     ${classNameSelector} { 
       background-color: #ccc;
       padding: .5em 1em;
     }
-    [class="${className}"] > strong {
+    [class="${classNameRaw}"] > strong {
       color: #c00;
     }
     @media (min-width: 800px) {
@@ -799,9 +817,12 @@ export const myOtherClass = vanillaClass(
         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/vanillaExtract.d.ts

@@ -12,9 +12,20 @@ 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 = (className: string, classNameSelector: string) => string;
+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
  */

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, `.${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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.34",
+	"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,9 +12,20 @@ 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 = (className: string, classNameSelector: string) => string;
+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
  */

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, `.${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;
 // ---------------------------------------------------------------------------