js-style-kit 0.6.1 → 0.7.0

package/src/eslint/unicorn/rules.ts

@@ -0,0 +1,86 @@
+import type { EslintRuleConfig, FilenameCase } from "../types.js";
+
+type UnicornRules = Record<`unicorn/${string}`, EslintRuleConfig>;
+
+/**
+ * Generate Unicorn ESLint rules with configurable filename case.
+ *
+ * @param filenameCase - The filename case to enforce. Defaults to "kebabCase".
+ * @returns Unicorn ESLint rules configuration.
+ */
+export const rules = (
+  filenameCase: FilenameCase = "kebabCase",
+): UnicornRules => ({
+  /**
+   * Enforce better string content.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/better-regex.md
+   */
+  "unicorn/better-regex": "warn",
+  /**
+   * Enforce passing a message value when creating a built-in error.
+   *
+   * 🚫 Not fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/error-message.md
+   */
+  "unicorn/error-message": "warn",
+  /**
+   * Require consistent filename case for all linted files.
+   *
+   * 🚫 Not fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/filename-case.md
+   */
+  "unicorn/filename-case": [
+    "warn",
+    {
+      case: filenameCase,
+    },
+  ],
+  /**
+   * Enforce the use of new for all builtins, except String, Number, Boolean, Symbol and BigInt.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/new-for-builtins.md
+   */
+  "unicorn/new-for-builtins": "warn",
+  "unicorn/no-console-spaces": "warn",
+  /**
+   * Enforce using for-loop instead of while-loop.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-for-loop.md
+   */
+  "unicorn/no-for-loop": "warn",
+  /**
+   * Enforce the use of addEventListener and removeEventListener over on-functions.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prefer-add-event-listener.md
+   */
+  "unicorn/prefer-add-event-listener": "warn",
+  /**
+   * Require using the `node:` protocol when importing Node.js built-in modules.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prefer-node-protocol.md
+   */
+  "unicorn/prefer-node-protocol": "warn",
+  /**
+   * Prefer String#replaceAll() over String#replace() with a global regExp.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prefer-string-replace-all.md
+   */
+  "unicorn/prefer-string-replace-all": "warn",
+  /**
+   * Enforce throwing TypeError in type checking conditions.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prefer-type-error.md
+   */
+  "unicorn/prefer-type-error": "warn",
+  /**
+   * Enforce consistent brace style for case clauses.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/switch-case-braces.md
+   */
+  "unicorn/switch-case-braces": ["warn", "always"],
+  /**
+   * Enforce consistent case for text encoding identifiers.
+   *
+   * 🔧 Fixable - https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/text-encoding-identifier-case.md
+   */
+  "unicorn/text-encoding-identifier-case": "warn",
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./eslint/index.js";
+export type * from "./eslint/types.js";
+export * from "./prettier/index.js";

package/src/modules.d.ts

@@ -0,0 +1,5 @@
+declare module "eslint-plugin-import" {}
+
+declare module "eslint-plugin-react-hooks" {}
+
+declare module "eslint-plugin-react-compiler" {}

package/src/prettier/README.md

@@ -0,0 +1,413 @@
+# Prettier Configuration
+
+Opinionated Prettier configuration with powerful plugins for CSS ordering, JSON sorting, Tailwind class sorting, and more.
+
+[← Back to main README](../../README.md)
+
+## Overview
+
+The Prettier configuration includes:
+
+- **Faster parser** - OXC parser for improved performance (optional)
+- **CSS ordering** - Consistent property order
+- **Curly braces** - Enforce braces for all control statements
+- **JSON sorting** - Alphabetical key sorting
+- **Package.json** - Consistent dependency ordering
+- **Tailwind CSS** - Class name sorting (optional)
+
+## Quick Start
+
+```js
+// @ts-check
+import { prettierConfig } from "js-style-kit";
+
+export default prettierConfig();
+```
+
+## Configuration Options
+
+```js
+// @ts-check
+import { prettierConfig } from "js-style-kit";
+
+export default prettierConfig({
+  // Plugin options (all boolean or config object)
+  cssOrderPlugin: true, // Sort CSS properties
+  curlyPlugin: true, // Enforce curly braces
+  jsonSortPlugin: true, // Sort JSON keys
+  packageJsonPlugin: true, // Sort package.json
+  tailwindPlugin: false, // Tailwind class sorting
+  parser: "oxc", // "oxc" (faster) or "default"
+
+  // Standard Prettier options
+  printWidth: 80,
+  tabWidth: 2,
+  semi: true,
+  singleQuote: false,
+  trailingComma: "all",
+  // ... any Prettier option
+});
+```
+
+## Parser Options
+
+### OXC Parser (Default)
+
+The **OXC parser** is a faster alternative to Prettier's default parser:
+
+```js
+// @ts-check
+export default prettierConfig({
+  parser: "oxc", // Default - faster performance
+});
+```
+
+**Benefits:**
+
+- ⚡ Significantly faster than default parser
+- ✅ 100% compatible with Prettier
+- ✅ Written in Rust for performance
+
+### Default Parser
+
+Use Prettier's standard parser:
+
+```js
+// @ts-check
+export default prettierConfig({
+  parser: "default", // Standard Prettier parser
+});
+```
+
+## Plugin Features
+
+### CSS Property Ordering
+
+**Enabled by default** - Sorts CSS properties in a consistent order:
+
+```css
+/* ✅ Good - properties sorted */
+.button {
+  display: flex;
+  align-items: center;
+  border-radius: 4px;
+  background-color: blue;
+  padding: 1rem;
+}
+
+/* Before formatting - unsorted */
+.button {
+  display: flex;
+  align-items: center;
+  border-radius: 4px;
+  background-color: blue;
+  padding: 1rem;
+}
+```
+
+Disable:
+
+```js
+cssOrderPlugin: false;
+```
+
+### Curly Braces Enforcement
+
+**Enabled by default** - Enforces curly braces for all control statements:
+
+```js
+// ✅ Good - always has braces
+if (condition) {
+  doSomething();
+}
+
+for (const item of items) {
+  process(item);
+}
+
+// Before formatting - missing braces
+if (condition) doSomething();
+for (const item of items) process(item);
+```
+
+This is equivalent to ESLint's `curly: "all"` rule but applied at the formatting level.
+
+Disable:
+
+```js
+curlyPlugin: false;
+```
+
+### JSON Sorting
+
+**Enabled by default** - Sorts JSON object keys alphabetically:
+
+```json
+// ✅ Good - keys sorted
+{
+  "apiUrl": "https://api.example.com",
+  "environment": "production",
+  "features": {
+    "analytics": true,
+    "darkMode": false
+  },
+  "timeout": 5000
+}
+
+// Before formatting - unsorted
+{
+  "timeout": 5000,
+  "environment": "production",
+  "features": {
+    "darkMode": false,
+    "analytics": true
+  },
+  "apiUrl": "https://api.example.com"
+}
+```
+
+**Recursive sorting** is enabled by default (sorts nested objects too).
+
+#### Customize JSON Sorting
+
+```js
+jsonSortPlugin: {
+  jsonRecursiveSort: true,        // Sort nested objects
+  jsonSortOrder: "{ ... }",       // Custom sort order (advanced)
+}
+```
+
+#### Disable
+
+```js
+jsonSortPlugin: false;
+```
+
+### Package.json Sorting
+
+**Enabled by default** - Sorts package.json with smart dependency ordering:
+
+```json
+{
+  "name": "my-package",
+  "version": "1.0.0",
+  "description": "...",
+  "main": "index.js",
+  "scripts": { ... },
+  "dependencies": { ... },
+  "devDependencies": { ... }
+}
+```
+
+Follows npm/yarn conventions for field ordering.
+
+Disable:
+
+```js
+packageJsonPlugin: false;
+```
+
+### Tailwind CSS Class Sorting
+
+**Disabled by default** - Sorts Tailwind classes following official recommendations:
+
+```jsx
+// ✅ Good - classes sorted
+<div className="flex items-center justify-between p-4 bg-blue-500 rounded-lg" />
+
+// Before formatting - unsorted
+<div className="p-4 bg-blue-500 flex rounded-lg items-center justify-between" />
+```
+
+#### Enable with path to global css file for Tailwind v4
+
+```js
+tailwindPlugin: "./src/index.css";
+```
+
+#### Specify Utility Functions
+
+```js
+tailwindPlugin: ["clsx", "cva", "cn", "myCustomUtil"];
+```
+
+#### Advanced Configuration
+
+```js
+tailwindPlugin: {
+  tailwindFunctions: ["clsx", "cva", "tw"],
+  tailwindAttributes: ["className", "class", "tw"],
+  tailwindStylesheet: "./styles/tailwind.css",
+}
+```
+
+## Standard Prettier Options
+
+All standard Prettier options are supported:
+
+```js
+export default prettierConfig({
+  // Plugins (documented above)
+  tailwindPlugin: true,
+
+  // Standard options
+  printWidth: 100, // Line length
+  tabWidth: 2, // Spaces per tab
+  useTabs: false, // Use spaces
+  semi: true, // Semicolons
+  singleQuote: false, // Double quotes
+  quoteProps: "as-needed", // Quote object properties
+  trailingComma: "all", // Trailing commas
+  bracketSpacing: true, // { foo: bar }
+  bracketSameLine: false, // JSX bracket on new line
+  arrowParens: "always", // (x) => x
+  endOfLine: "lf", // Unix line endings
+  proseWrap: "preserve", // Markdown wrapping
+});
+```
+
+## Common Configurations
+
+### Minimal (Disable Plugins)
+
+```js
+export default prettierConfig({
+  cssOrderPlugin: false,
+  curlyPlugin: false,
+  jsonSortPlugin: false,
+  packageJsonPlugin: false,
+  parser: "default",
+});
+```
+
+### Tailwind Project
+
+```js
+export default prettierConfig({
+  tailwindPlugin: true,
+  printWidth: 100,
+  singleQuote: true,
+});
+```
+
+### Library/Package
+
+```js
+export default prettierConfig({
+  packageJsonPlugin: true,
+  jsonSortPlugin: true,
+  singleQuote: true,
+  trailingComma: "es5",
+});
+```
+
+### Next.js Project
+
+```js
+export default prettierConfig({
+  tailwindPlugin: {
+    tailwindFunctions: ["cn", "clsx"],
+  },
+  printWidth: 100,
+});
+```
+
+## Package.json Scripts
+
+Add these scripts to your package.json:
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}
+```
+
+Run `format:check` in CI to verify formatting.
+
+## VS Code Integration
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true
+}
+```
+
+## Ignore Files
+
+Create `.prettierignore`:
+
+```
+# Dependencies
+node_modules
+.pnpm-store
+
+# Build outputs
+dist
+build
+.next
+out
+
+# Misc
+coverage
+.cache
+```
+
+## Plugin Documentation
+
+Each plugin has additional options:
+
+- **OXC Parser** - [Documentation](https://www.npmjs.com/package/@prettier/plugin-oxc)
+- **CSS Order** - [Documentation](https://www.npmjs.com/package/prettier-plugin-css-order)
+- **Curly** - [Documentation](https://www.npmjs.com/package/prettier-plugin-curly)
+- **JSON Sort** - [Documentation](https://www.npmjs.com/package/prettier-plugin-sort-json)
+- **Package.json** - [Documentation](https://www.npmjs.com/package/prettier-plugin-packagejson)
+- **Tailwind** - [Documentation](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
+
+## Troubleshooting
+
+### Prettier not formatting
+
+1. Check `.prettierignore` isn't excluding files
+2. Verify VS Code is using the right formatter
+3. Check for conflicting Prettier configs
+
+### Tailwind classes not sorting
+
+1. Ensure `tailwindPlugin` is set to your global css file path
+2. Reload your IDE
+3. Run the prettier CLI to see if there's an error
+
+### OXC parser issues
+
+Switch to default parser:
+
+```js
+parser: "default";
+```
+
+### Plugin conflicts
+
+Disable plugins one-by-one to identify conflicts:
+
+```js
+cssOrderPlugin: false,
+curlyPlugin: false,
+// etc.
+```
+
+## Learn More
+
+- [Prettier Documentation](https://prettier.io/docs/en/)
+- [Main README](../../README.md)

package/src/prettier/index.ts

@@ -0,0 +1,110 @@
+import type { Config as PrettierConfig } from "prettier";
+import type { SortJsonOptions as SortJsonPluginOptions } from "prettier-plugin-sort-json";
+import type { PluginOptions as TailwindPluginOptions } from "prettier-plugin-tailwindcss";
+
+import { isObject, isString } from "../utils/is-type.js";
+
+export interface PrettierConfigOptions extends PrettierConfig {
+  cssOrderPlugin?: boolean;
+  curlyPlugin?: boolean;
+  jsonSortPlugin?: boolean | SortJsonPluginOptions;
+  packageJsonPlugin?: boolean;
+  parser?: "default" | "oxc";
+  tailwindPlugin?: boolean | string | TailwindPluginOptions;
+}
+
+export interface PrettierConfigWithPlugins
+  extends PrettierConfig,
+    SortJsonPluginOptions,
+    TailwindPluginOptions {}
+
+/**
+ * Creates a Prettier configuration object with optional Tailwind support
+ *
+ * @param options - Configuration options for Prettier
+ * @param options.cssOrderPlugin CSS order sorting support
+ * @param options.curlyPlugin Enforce curly braces for all control statements
+ * @param options.jsonSortPlugin JSON sorting support
+ * @param options.parser choose between default and oxc parser
+ * @param options.packageJsonPlugin Package.json sorting support
+ * @param options.tailwindPlugin Tailwind CSS formatting support
+ * @returns Prettier configuration object with:
+ * - Default Prettier configuration
+ * - Experimental ternaries enabled
+ * - OXC parser plugin
+ * - CSS order plugin
+ * - Curly braces plugin
+ * - JSON sorting plugin
+ * - Package.json sorting plugin
+ * - Optional Tailwind plugin and functions
+ */
+export const prettierConfig = (
+  options: PrettierConfigOptions = {},
+): PrettierConfigWithPlugins => {
+  const {
+    cssOrderPlugin = true,
+    curlyPlugin = true,
+    jsonSortPlugin = true,
+    packageJsonPlugin = true,
+    parser = "oxc",
+    tailwindPlugin = false,
+    ...rest
+  } = options;
+
+  const plugins: string[] = [];
+  const config: PrettierConfigWithPlugins = {
+    experimentalTernaries: true,
+    ...rest,
+  };
+
+  if (parser === "oxc") {
+    plugins.push("@prettier/plugin-oxc");
+  }
+
+  if (cssOrderPlugin) {
+    plugins.push("prettier-plugin-css-order");
+  }
+
+  if (curlyPlugin) {
+    plugins.push("prettier-plugin-curly");
+  }
+
+  if (jsonSortPlugin) {
+    plugins.push("prettier-plugin-sort-json");
+
+    if (isObject(jsonSortPlugin)) {
+      Object.assign(config, jsonSortPlugin);
+    } else {
+      config.jsonRecursiveSort = true;
+    }
+  }
+
+  if (packageJsonPlugin) {
+    plugins.push("prettier-plugin-packagejson");
+  }
+
+  if (tailwindPlugin) {
+    plugins.push("prettier-plugin-tailwindcss");
+    const defaultTailwindFunctions = ["clsx", "cva", "cn"];
+
+    if (isString(tailwindPlugin)) {
+      // then it's the path to the stylesheet
+      config.tailwindStylesheet = tailwindPlugin;
+      config.tailwindFunctions = defaultTailwindFunctions;
+    } else if (isObject(tailwindPlugin)) {
+      Object.assign(config, tailwindPlugin);
+
+      // Ensure defaultTailwindFunctions is applied if tailwindFunctions wasn't specified
+      if (!tailwindPlugin.tailwindFunctions) {
+        config.tailwindFunctions = defaultTailwindFunctions;
+      }
+    } else {
+      config.tailwindFunctions = defaultTailwindFunctions;
+    }
+  }
+
+  // Set plugins after all configurations are done
+  config.plugins = plugins;
+
+  return config;
+};

package/src/utils/is-type.ts

@@ -0,0 +1,60 @@
+/**
+ * Type predicate for string values
+ *
+ * @param value - The value to check
+ * @returns True if the value is a string, false otherwise
+ */
+export const isString = (value: unknown): value is string => {
+  return typeof value === "string";
+};
+
+/**
+ * Type predicate for number values
+ *
+ * @param value - The value to check
+ * @returns True if the value is a number and not NaN, false otherwise
+ */
+export const isNumber = (value: unknown): value is number => {
+  return typeof value === "number" && !Number.isNaN(value);
+};
+
+/**
+ * Type predicate for boolean values
+ *
+ * @param value - The value to check
+ * @returns True if the value is a boolean, false otherwise
+ */
+export const isBoolean = (value: unknown): value is boolean => {
+  return typeof value === "boolean";
+};
+
+/**
+ * Type predicate for array values
+ *
+ * @param value - The value to check
+ * @returns True if the value is an array, false otherwise
+ */
+export const isArray = <T = unknown>(value: unknown): value is T[] => {
+  return Array.isArray(value);
+};
+
+/**
+ * Type predicate for object values (excluding null and arrays)
+ *
+ * @param value - The value to check
+ * @returns True if the value is an object (not null and not an array), false otherwise
+ */
+export const isObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+
+/**
+ * Type predicate for function values
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function, false otherwise
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export const isFunction = (value: unknown): value is Function => {
+  return typeof value === "function";
+};