feat: initial code for calc and vars

.gitignore

@@ -1,57 +1,5 @@
-# build output
-dist
-!.github/actions/*/dist
-.next
-target
-packages/next/wasm/@next
-tarballs/
-packages/**/*.tgz
-
-# dependencies
 node_modules
-package-lock.json
-yarn.lock
-!/yarn.lock
-test/node_modules
-.pnpm-store/
-.github/**/node_modules
-
-# logs & pids
-*.log
-pids
-*.cpuprofile
-*.heapsnapshot
-
-# coverage
-.nyc_output
-coverage
-
-# test output
-test/**/out*
-test/**/next-env.d.ts
+dist
 .DS_Store
-/e2e-tests
-test/tmp/**
-test/.trace
-test/traces
-
-# Editors
-**/.idea
-**/.#*
-.nvmrc
-
-# examples
-examples/**/out
-examples/**/.env*.local
-
-pr-stats.md
-test-timings.json
-
-# Vercel
-.vercel
-.now
-
-# Cache
-*.tsbuildinfo
-.swc/
-.turbo
+*.log
+coverage

.npmignore

@@ -0,0 +1,8 @@
+src/
+tests/
+coverage/
+*.test.ts
+*.test.tsx
+tsconfig.json
+.eslintrc*
+vitest.config.ts

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2024 Jesse McLean
+Copyright (c) 2021 SEEK
+Copyright (c) 2024 Jesse McLean, Built by Field
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,110 @@
-# css-utils
-
+# @builtbyfield/css-utils
+
+A collection of type-safe utilities for working with CSS in TypeScript applications.
+
+## Features
+
+- **CSS Variables Utility**: Type-safe creation and manipulation of CSS Custom Properties
+- **CSS Calc Utility**: Chainable API for creating CSS `calc()` expressions
+- Zero runtime dependencies (except for `cssesc` for proper CSS escaping)
+- Comprehensive TypeScript support
+- Thoroughly tested utilities
+
+## Installation
+
+```bash
+# Using npm
+npm install @builtbyfield/css-utils
+
+# Using yarn
+yarn add @builtbyfield/css-utils
+
+# Using pnpm
+pnpm add @builtbyfield/css-utils
+```
+
+## Modules
+
+### CSS Variables Utility
+
+Create and manage CSS Custom Properties with type safety:
+
+```typescript
+import { createCSSVar, fallbackCSSVar } from '@builtbyfield/css-utils'
+
+// Simple variable
+const bgColor = createCSSVar('background-color')
+// Result: var(--background-color)
+
+// With fallback
+const textColor = createCSSVar('text-color', { fallback: '#000' })
+// Result: var(--text-color, #000)
+
+// Fallback chain
+const color = fallbackCSSVar('--primary', '--secondary', '#default')
+// Result: var(--primary, var(--secondary, #default))
+```
+
+[Read more about CSS Variables Utility](src/vars/README.md)
+
+### CSS Calc Utility
+
+Create complex CSS calculations with a chainable API:
+
+```typescript
+import { calc } from '@builtbyfield/css-utils'
+
+// Basic operations
+calc.add('100px', '20px') // calc(100px + 20px)
+
+// Chainable operations
+calc('100vh')
+  .subtract('20px')
+  .multiply(0.5)
+  .toString() // calc((100vh - 20px) * 0.5)
+```
+
+[Read more about CSS Calc Utility](src/calc/README.md)
+
+## Type Safety
+
+The library provides comprehensive TypeScript types for all utilities:
+
+```typescript
+import type {
+  // CSS Variables types
+  CSSVarDefinition,
+  CSSVarFunction,
+  CSSVarName,
+  CSSVarOptions,
+
+  // CSS Calc types
+  Operator,
+  Operand,
+  CalcChain
+} from '@builtbyfield/css-utils'
+```
+
+## Error Handling
+
+Both utilities include robust error handling:
+
+- Validation of CSS variable names
+- Type checking for calc operations
+- Descriptive error messages
+- Runtime checks for invalid inputs
+
+## Browser Support
+
+This library is designed for modern browsers that support:
+- CSS Custom Properties (CSS Variables)
+- CSS `calc()` function
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- CSS Calc utility was inspired by [@vanilla-extract/css-utils](https://github.com/vanilla-extract-css/vanilla-extract/tree/master/packages/utils)
+- CSS Variables utility was loosely inspired by [vanilla-extract](https://vanilla-extract.style/)'s `vars.ts`

eslint.config.mjs

@@ -0,0 +1,23 @@
+import pluginJs from "@eslint/js";
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  { files: ["**/*.{js,mjs,cjs,ts}"] },
+  { languageOptions: { globals: { ...globals.browser, ...globals.node } } },
+  {
+    plugins: {
+      "simple-import-sort": simpleImportSort,
+    },
+  },
+  {
+    rules: {
+      "simple-import-sort/imports": "warn",
+      "simple-import-sort/exports": "warn",
+    },
+  },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+];

package.json

@@ -1,16 +1,66 @@
 {
-  "name": "css-utils",
+  "name": "@builtbyfield/css-utils",
   "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "description": "CSS utility functions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:manual": "vite",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
   },
-  "keywords": [],
+  "dependencies": {
+    "cssesc": "^3.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.0.1",
+    "@types/cssesc": "^3.0.2",
+    "@types/node": "^22.9.3",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitest/coverage-v8": "latest",
+    "eslint": "^9.15.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^15.12.0",
+    "happy-dom": "^15.11.6",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.15.0",
+    "vite": "^5.4.11",
+    "vitest": "latest"
+  },
+  "keywords": [
+    "css",
+    "typescript",
+    "calc",
+    "vars",
+    "custom properties"
+  ],
   "author": {
     "name": "Jesse McLean",
     "email": "[email protected]",
     "url": "https://builtbyfield.com"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/builtbyfield/css-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/builtbyfield/css-utils/issues"
+  },
+  "homepage": "https://github.com/builtbyfield/css-utils"
 }