feat: Better examples. Work-in-progress.

Author: chriseppstein

packages/@css-blocks/jsx/.vscode/launch.json

@@ -9,7 +9,7 @@
       "request": "launch",
       "name": "Launch Program",
       "preLaunchTask": "compile",
-      "program": "${workspaceRoot}/node_modules/.bin/_mocha",
+      "program": "${workspaceRoot}/../../../node_modules/.bin/_mocha",
       "args": [
         "dist/test",
         "--recursive",

packages/@css-blocks/jsx/src/Analyzer/index.ts

@@ -1,40 +1,64 @@
-import {
-  Analysis,
-  Analyzer,
-  Block,
-} from "@css-blocks/core";
+import { Analysis, Analyzer, Block } from "@css-blocks/core";
 import { TemplateIntegrationOptions } from "@opticss/template-api";
 import { some, unwrap } from "@opticss/util";
 import traverse from "babel-traverse";
 import * as babylon from "babylon";
 import * as debugGenerator from "debug";
 import * as fs from "fs-extra";
 import * as path from "path";
+import { deprecate } from "util";
 
-import { CssBlocksJSXOptions } from "../options";
+import { JSXOptions, JSXOptionsReader } from "../options";
 import { JSXParseError } from "../utils/Errors";
 
 import { JSXTemplate, TEMPLATE_TYPE } from "./Template";
 import { elementVisitor, importVisitor } from "./visitors";
 
-const debug = debugGenerator("css-blocks:jsx:Analyzer");
-
 export type JSXAnalysis = Analysis<TEMPLATE_TYPE>;
 
+export interface AnalyzerOptions {
+  /** A name that is used (if provided) in logging to distinguish output of different analyzers in a build. */
+  analyzerName?: string;
+}
+
+const deprecatedName = deprecate(
+  (name: string, options: JSXOptions & AnalyzerOptions) => {
+    options.analyzerName = name;
+  },
+  "The name parameter of the JSX Analyzer is deprecated and usually unnecessary.\n" +
+  "Pass only options and set the analyzerName option there if you really need it (you really don't).",
+);
+
 export class CSSBlocksJSXAnalyzer extends Analyzer<TEMPLATE_TYPE> {
-  private options: CssBlocksJSXOptions;
+  private options: JSXOptionsReader;
 
-  public name: string;
+  public name?: string;
   public analysisPromises: Map<string, Promise<JSXAnalysis>>;
   public blockPromises: Map<string, Promise<Block>>;
+  private debug: debugGenerator.IDebugger;
 
-  constructor(name: string, options: Partial<CssBlocksJSXOptions> = {}) {
-    let opts = new CssBlocksJSXOptions(options);
-    super(opts.compilationOptions);
-    this.name = name;
-    this.options = opts;
+  constructor(options: JSXOptions & AnalyzerOptions);
+  /**
+   * @deprecated Use the single argument constructor.
+   * @param name Deprecated. Pass the analyzerName option instead;
+   */
+  constructor(name: string | JSXOptions & AnalyzerOptions, options: JSXOptions & AnalyzerOptions = {}) {
+    // ewww need to get rid of this deprecation soon.
+    super(options && options.compilationOptions || (name && typeof name !== "string" && name.compilationOptions) || {});
+    if (typeof name === "string") {
+      deprecatedName(name, options);
+    } else {
+      options = name;
+    }
+    this.name = options.analyzerName;
+    this.options = new JSXOptionsReader(options);
     this.analysisPromises = new Map();
     this.blockPromises = new Map();
+    let debugIdent = "css-blocks:jsx:Analyzer";
+    if (this.name) {
+      debugIdent += `:${this.name}`;
+    }
+    this.debug = debugGenerator(debugIdent);
   }
 
   public reset() {
@@ -67,7 +91,7 @@ export class CSSBlocksJSXAnalyzer extends Analyzer<TEMPLATE_TYPE> {
       promises.push(this.parseFile(path.join(dir, entryPoint)));
     }
     await Promise.all(promises);
-    debug(`Found ${this.analysisPromises.size} analysis promises`);
+    this.debug(`Found ${this.analysisPromises.size} analysis promises`);
     return this;
   }
 
@@ -105,11 +129,11 @@ export class CSSBlocksJSXAnalyzer extends Analyzer<TEMPLATE_TYPE> {
     process.chdir(oldDir);
 
     // Wait for all block promises to resolve then resolve with the finished analysis.
-    debug(`Waiting for ${blockPromises.length} Block imported by "${template.identifier}" to finish compilation.`);
+    this.debug(`Waiting for ${blockPromises.length} Block imported by "${template.identifier}" to finish compilation.`);
     await Promise.all(blockPromises);
-    debug(`Waiting for ${childTemplatePromises.length} child templates to finish analysis before analysis of ${template.identifier}.`);
+    this.debug(`Waiting for ${childTemplatePromises.length} child templates to finish analysis before analysis of ${template.identifier}.`);
     await Promise.all(childTemplatePromises);
-    debug(`All child compilations finished for "${template.identifier}".`);
+    this.debug(`All child compilations finished for "${template.identifier}".`);
     return analysis;
 
   }
@@ -123,11 +147,11 @@ export class CSSBlocksJSXAnalyzer extends Analyzer<TEMPLATE_TYPE> {
 
     let template: JSXTemplate = new JSXTemplate(filename, data);
 
-    debug(`Beginning imports crawl of ${filename}.`);
+    this.debug(`Beginning imports crawl of ${filename}.`);
     let analysisPromise = this.crawl(template);
     this.analysisPromises.set(template.identifier, analysisPromise);
     let analysis = await analysisPromise;
-    debug(`Finished imports crawl of ${filename}.`);
+    this.debug(`Finished imports crawl of ${filename}.`);
 
     traverse(unwrap(analysis.template.ast), elementVisitor(analysis));
       // No need to keep detailed template data anymore!

packages/@css-blocks/jsx/src/Analyzer/visitors/importer.ts

@@ -18,7 +18,7 @@ import {
 import * as debugGenerator from "debug";
 
 import { JSXTemplate, TEMPLATE_TYPE } from "../../Analyzer/Template";
-import { CssBlocksJSXOptions } from "../../options";
+import { JSXOptionsReader } from "../../options";
 import { ErrorLocation, TemplateImportError } from "../../utils/Errors";
 import { isBlockFilename } from "../../utils/isBlockFilename";
 import { CSSBlocksJSXAnalyzer } from "../index";
@@ -58,7 +58,7 @@ export function importVisitor(
   analysis: Analysis<TEMPLATE_TYPE>,
   blockPromises: Promise<Block>[],
   childTemplatePromises: Promise<Analysis<TEMPLATE_TYPE>>[],
-  options: CssBlocksJSXOptions,
+  options: JSXOptionsReader,
 ) {
 
   // Keep a running record of local block names while traversing so we can check

packages/@css-blocks/jsx/src/index.ts

@@ -1,3 +1,3 @@
-export { CSSBlocksJSXAnalyzer as Analyzer } from "./Analyzer";
+export { CSSBlocksJSXAnalyzer as Analyzer, AnalyzerOptions } from "./Analyzer";
 export { CSSBlocksJSXTransformer as Rewriter } from "./transformer";
-export { CssBlocksJSXOptions as Options } from "./options";
+export { JSXOptions as Options, JSXOptionsReader as OptionReader } from "./options";

packages/@css-blocks/jsx/src/options.ts

@@ -1,6 +1,5 @@
-import { ResolvedConfiguration, resolveConfiguration } from "@css-blocks/core";
+import { Configuration as CSSBlocksConfiguration, ResolvedConfiguration, resolveConfiguration } from "@css-blocks/core";
 import { ObjectDictionary } from "@opticss/util";
-
 import { BabylonOptions, PluginName } from "babylon";
 
 // We are only using the output Babylon AST to collect analysis data here,
@@ -32,14 +31,22 @@ const BABEL_PLUGINS: any = [
   "nullishCoalescingOperator",
 ];
 
-export class CssBlocksJSXOptions {
+export interface JSXOptions {
+  baseDir?: string;
+  types?: "typescript" | "flow" | "none";
+  aliases?: ObjectDictionary<string>;
+  compilationOptions?: CSSBlocksConfiguration;
+  // resolver?: (importPath: string, fromFile?: string) => string;
+}
+
+export class JSXOptionsReader {
   public baseDir: string;
-  public types: "typescript" | "flow" | "none";
+  public types: JSXOptions["types"];
   public aliases: ObjectDictionary<string>;
   public compilationOptions: ResolvedConfiguration;
   public parserOptions: BabylonOptions;
 
-  constructor(opts: Partial<CssBlocksJSXOptions>) {
+  constructor(opts: JSXOptions = {}) {
     this.baseDir = opts.baseDir || ".";
     this.types = opts.types || "none";
     this.aliases = opts.aliases || {};

packages/@css-blocks/jsx/src/transformer/babel.ts

@@ -26,6 +26,7 @@ import {
 } from "babel-types";
 // import { TemplateAnalysisError } from '../utils/Errors';
 import * as debugGenerator from "debug";
+import { deprecate } from "util";
 
 import { TEMPLATE_TYPE } from "../Analyzer/Template";
 import { JSXElementAnalyzer } from "../Analyzer/visitors/element";
@@ -62,8 +63,7 @@ interface BabelFile {
     filename: string;
   };
 }
-
-export function makePlugin(transformOpts: { rewriter: Rewriter }): () => PluginObj<CssBlocksVisitor> {
+export function babelPlugin(transformOpts: { rewriter: Rewriter }): () => PluginObj<CssBlocksVisitor> {
   const rewriter = transformOpts.rewriter;
   debug(`Made Rewriter`);
 
@@ -199,6 +199,11 @@ export function makePlugin(transformOpts: { rewriter: Rewriter }): () => PluginO
   };
 }
 
+/**
+ * @deprecated call babelPlugin instead.
+ */
+export const makePlugin = deprecate(babelPlugin, "makePlugin has been renamed babelPlugin");
+
 function detectStrayReferenceToImport(
   importDeclPath: NodePath<ImportDeclaration>,
   filename: string,

packages/@css-blocks/jsx/test/transformer/transformer-test.ts

@@ -14,7 +14,7 @@ import * as testConsole from "test-console";
 
 import { Rewriter } from "../../src";
 import { CSSBlocksJSXAnalyzer as Analyzer } from "../../src/Analyzer";
-import { makePlugin } from "../../src/transformer/babel";
+import { babelPlugin } from "../../src/transformer/babel";
 import { testParse as parse } from "../util";
 
 const mock = require("mock-fs");
@@ -43,7 +43,7 @@ function transform(code: string, analysis: Analysis<"Opticss.JSXTemplate">, cssB
     let babelResult = babel.transform(code, {
       filename: filename,
       plugins: [
-        makePlugin({rewriter}),
+        babelPlugin({rewriter}),
       ],
       parserOpts: { plugins: [ "jsx" ] },
     });

packages/@css-blocks/jsx/test/util.ts

@@ -1,13 +1,17 @@
-import { Analyzer, Options } from "../src/index";
+import { Analyzer, AnalyzerOptions, Options } from "../src/index";
 
-export async function testParse(data: string, filename = "", opts?: Partial<Options>): Promise<Analyzer> {
-  let analyzer = new Analyzer("test-analyzer", opts);
+export async function testParse(data: string, filename = "", opts?: Options): Promise<Analyzer> {
+  let analyzerOptions: Options & AnalyzerOptions = opts || {};
+  analyzerOptions.analyzerName = "test-analyzer";
+  let analyzer = new Analyzer(analyzerOptions);
   await analyzer.parse(filename, data);
   return analyzer;
 }
 
-export async function testParseFile(file: string, opts?: Partial<Options>): Promise<Analyzer> {
-  let analyzer = new Analyzer("test-analyzer", opts);
+export async function testParseFile(file: string, opts?: Options): Promise<Analyzer> {
+  let analyzerOptions: Options & AnalyzerOptions = opts || {};
+  analyzerOptions.analyzerName = "test-analyzer";
+  let analyzer = new Analyzer(analyzerOptions);
   await analyzer.parseFile(file);
   return analyzer;
 }

packages/@css-blocks/webpack/README.md

@@ -81,6 +81,11 @@ Each template integration's rewriter is slightly different and must be integrate
 However, Webpack will typically be used with CSS Blocks' JSX integration. The typical JSX end-to-end integration with webpack looks like this:
 
 ```js
+const path = require("path");
+const appDirectory = fs.realpathSync(process.cwd());
+const paths = {
+  appIndexJs: path.resolve(appDirectory, "src/index.tsx"),
+};
 
 const jsxCompilationOptions = {
   compilationOptions: {},

packages/@css-blocks/webpack/examples/build.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+EXAMPLES=jsx
+
+for example in $EXAMPLES; do
+  cd $example
+  rm -rf node_modules/@css-blocks
+  yarn && yarn build || exit 1
+  cd -
+done