@reykjavik/webtools 0.1.31 → 0.1.33

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;