💥 localsConvention option (#17)

Replaces `--dashes` option with proper `--localsConvention` option that
matches PostCSS and other libraries. Changes the default to `dashesOnly`
which roughly matches the previous `--dashes` implementation.

BREAKING CHANGE: CLI change

Adds `lodash.camelcase` to match PostCSS implementation.

+semver:minor (0.x semver)

Closes #2

Author: connorjs

.github/workflows/pipeline.yaml

@@ -78,18 +78,18 @@ jobs:
       - name: Run css-typed (the test)
         # `node dist/main.js` is executing local `css-typed` as if installed (same as `bin`)
         # Use `-I '//.*'` to ignore the first line (comment) which has generated path and timestamp
-        # Test --dashes in both positions
+        # Test `--localsConvention` in both positions
         run: |
-          cp src/fixtures/kebab-case/kebab-case.css "$RUNNER_TEMP/kebab-case.css"
+          cp src/fixtures/casing/casing.css "$RUNNER_TEMP/casing.css"
 
           node dist/main.js "$RUNNER_TEMP/*.css"
-          diff --strip-trailing-cr -uI '//.*' src/fixtures/kebab-case/kebab-case-default.d.css.ts "$RUNNER_TEMP/kebab-case.d.css.ts"
+          diff --strip-trailing-cr -uI '//.*' src/fixtures/casing/dashesOnly.d.css.ts "$RUNNER_TEMP/casing.d.css.ts"
 
-          node dist/main.js "$RUNNER_TEMP/*.css" --dashes
-          diff --strip-trailing-cr -uI '//.*' src/fixtures/kebab-case/kebab-case-dashes.d.css.ts "$RUNNER_TEMP/kebab-case.d.css.ts"
+          node dist/main.js "$RUNNER_TEMP/*.css" --localsConvention camelCaseOnly
+          diff --strip-trailing-cr -uI '//.*' src/fixtures/casing/camelCaseOnly.d.css.ts "$RUNNER_TEMP/casing.d.css.ts"
 
-          node dist/main.js --dashes "$RUNNER_TEMP/*.css" 
-          diff --strip-trailing-cr -uI '//.*' src/fixtures/kebab-case/kebab-case-dashes.d.css.ts "$RUNNER_TEMP/kebab-case.d.css.ts"
+          node dist/main.js --localsConvention camelCaseOnly "$RUNNER_TEMP/*.css" 
+          diff --strip-trailing-cr -uI '//.*' src/fixtures/casing/camelCaseOnly.d.css.ts "$RUNNER_TEMP/casing.d.css.ts"
 
   Publish:
     if: ${{ github.ref == 'refs/heads/main' }}

README.md

@@ -47,35 +47,44 @@ Configure TypeScript to allow arbitrary extensions (TS 5+).
 ```
 
 Add `*.d.css.ts` to your `.gitignore` if appropriate.
+(See [#4] for more information about alternative output directory.)
 
 ```shell
 echo '*.d.css.ts' >> .gitignore
 ```
 
+[#4]: https://github.com/connorjs/css-typed/issues/4
+
 ## Options
 
 The following table lists the options `css-typed` supports.
-Prior to the `1.0` release, these may change often.
+Also run `css-typed -h` on the command line.
 
-| CLI option | Description                               |
-| :--------: | :---------------------------------------- |
-| `--dashes` | Specifies the convention used for locals. |
+|      CLI option      |   Default    | Description                    |
+| :------------------: | :----------: | :----------------------------- |
+| `--localsConvention` | `dashesOnly` | Style of exported class names. |
 
-### Dashes
+### localsConvention
 
-_Inspired by [postcss’ localsConvention](https://github.com/madyankin/postcss-modules/tree/master#localsconvention).
-Prior to `v1.0`, this option will evolve to more closely match the `localsConvention` option._
+Inspired by [postcss localsConvention](https://github.com/madyankin/postcss-modules#localsconvention).
+Adds `none` option value to use the class name as-is.
 
-The `--dashes` option changes the style of exported classnames, the exports in your TS.
+The `--localsConvention` option changes the style of exported class names, the exports in your TS (i.e., the JS names).
 
-By default, `css-typed` will emit class names as-is if the name represents a valid JS/TS identifier.
-_Note: The logic for “valid” only checks hyphens (dashes, `-`) as of `v0.2.2`._
+`css-typed` will only camelize dashes in class names by default (the `dashesOnly` option value).
+It will not preserve the original class name.
+For example, `my-class` becomes `myClass` and you cannot use `my-class` in JS/TS code.
 
-When passed `dashes`, it will transform `kebab-case` classes (dashed names) to `camelCase`.
-For example, `my-class` becomes `myClass`.
+Modern bundlers or build system such as Vite and Gatsby support this transformation.
+The default matches CSS naming practices (`kebab-case`).
 
-Use `--dashes` when your bundler or build system supports that transformation.
-For example, Vite and Gatsby support this.
+> **IMPORTANT**
+>
+> Note that the non-`*Only` values MAY have TypeScript bugs.
+> TypeScript 5.6 may help with the named exports for these.
+>
+> If you encounter a bug, please file an issue.
+> In the mean-time, consider using `camelCaseOnly` instead (or `dashesOnly` which is the default).
 
 ## Recipes
 
@@ -86,8 +95,8 @@ To run it as part of your build, you will likely include it as a run script, may
 ```json
 {
 	"scripts": {
-		"codegen": "css-typed 'src/**/*.css'",
-		"pretsc": "css-typed 'src/**/*.css'",
+		"codegen": "css-typed \"src/**/*.css\"",
+		"pretsc": "css-typed \"src/**/*.css\"",
 		"tsc": "tsc"
 	}
 }
@@ -101,8 +110,8 @@ Feel free to [nodemon] or similar.
 ```json
 {
 	"scripts": {
-		"codegen": "css-typed 'src/**/*.css'",
-		"codegen:watch": "nodemon -x 'npm run codegen' -w src -e css"
+		"codegen": "css-typed \"src/**/*.css\"",
+		"codegen:watch": "nodemon -x \"npm run codegen\" -w src -e css"
 	}
 }
 ```

package-lock.json

@@ -47,7 +47,8 @@
 		"@commander-js/extra-typings": "^12.1.0",
 		"commander": "^12.1.0",
 		"css-tree": "^2.3.1",
-		"glob": "^11.0.0"
+		"glob": "^11.0.0",
+		"lodash.camelcase": "^4.3.0"
 	},
 	"devDependencies": {
 		"@types/css-tree": "^2.3.8",

package.json

@@ -0,0 +1,33 @@
+// Generated from `src/fixtures/casing/casing.css` by css-typed at $TIME
+
+const lowercase: string;
+const UPPERCASE: string;
+const uppercase: string;
+const camelCase: string;
+const PascalCase: string;
+const pascalCase: string;
+const _kebabcase: string;
+const kebabCase: string;
+const snake_case: string;
+const snakeCase: string;
+const SCREAM_CASE: string;
+const screamCase: string;
+const _TRAINCASE: string;
+const trainCase: string;
+
+export = {
+	lowercase,
+	UPPERCASE,
+	uppercase,
+	camelCase,
+	PascalCase,
+	pascalCase,
+	"kebab-case": _kebabcase,
+	kebabCase,
+	snake_case,
+	snakeCase,
+	SCREAM_CASE,
+	screamCase,
+	"TRAIN-CASE": _TRAINCASE,
+	trainCase,
+};

src/fixtures/casing/camelCase.d.css.ts

@@ -0,0 +1,10 @@
+// Generated from `src/fixtures/casing/casing.css` by css-typed at $TIME
+
+export const lowercase: string;
+export const uppercase: string;
+export const camelCase: string;
+export const pascalCase: string;
+export const kebabCase: string;
+export const snakeCase: string;
+export const screamCase: string;
+export const trainCase: string;

src/fixtures/casing/camelCaseOnly.d.css.ts

@@ -0,0 +1,12 @@
+/* Example classes with various casing conventions. */
+
+.lowercase,
+.UPPERCASE,
+.camelCase,
+.PascalCase,
+.kebab-case,
+.snake_case,
+.SCREAM_CASE,
+.TRAIN-CASE {
+	display: flex;
+}

src/fixtures/casing/casing.css

@@ -0,0 +1,25 @@
+// Generated from `src/fixtures/casing/casing.css` by css-typed at $TIME
+
+const lowercase: string;
+const UPPERCASE: string;
+const camelCase: string;
+const PascalCase: string;
+const _kebabcase: string;
+const kebabCase: string;
+const snake_case: string;
+const SCREAM_CASE: string;
+const _TRAINCASE: string;
+const TRAINCASE: string;
+
+export = {
+	lowercase,
+	UPPERCASE,
+	camelCase,
+	PascalCase,
+	"kebab-case": _kebabcase,
+	kebabCase,
+	snake_case,
+	SCREAM_CASE,
+	"TRAIN-CASE": _TRAINCASE,
+	TRAINCASE,
+};

src/fixtures/casing/dashes.d.css.ts

@@ -0,0 +1,10 @@
+// Generated from `src/fixtures/casing/casing.css` by css-typed at $TIME
+
+export const lowercase: string;
+export const UPPERCASE: string;
+export const camelCase: string;
+export const PascalCase: string;
+export const kebabCase: string;
+export const snake_case: string;
+export const SCREAM_CASE: string;
+export const TRAINCASE: string;

src/fixtures/casing/dashesOnly.d.css.ts

@@ -0,0 +1,21 @@
+// Generated from `src/fixtures/casing/casing.css` by css-typed at $TIME
+
+const lowercase: string;
+const UPPERCASE: string;
+const camelCase: string;
+const PascalCase: string;
+const _kebabcase: string;
+const snake_case: string;
+const SCREAM_CASE: string;
+const _TRAINCASE: string;
+
+export = {
+	lowercase,
+	UPPERCASE,
+	camelCase,
+	PascalCase,
+	"kebab-case": _kebabcase,
+	snake_case,
+	SCREAM_CASE,
+	"TRAIN-CASE": _TRAINCASE,
+};