Skip to content

Commit a429a7f

Browse files
essejmcleanessejmclean
committed
feat: initial code for calc and vars
1 parent 82bc18c commit a429a7f

23 files changed

+4359
-64
lines changed

‎.gitignore

Lines changed: 3 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,5 @@
1-
# build output
2-
dist
3-
!.github/actions/*/dist
4-
.next
5-
target
6-
packages/next/wasm/@next
7-
tarballs/
8-
packages/**/*.tgz
9-
10-
# dependencies
111
node_modules
12-
package-lock.json
13-
yarn.lock
14-
!/yarn.lock
15-
test/node_modules
16-
.pnpm-store/
17-
.github/**/node_modules
18-
19-
# logs & pids
20-
*.log
21-
pids
22-
*.cpuprofile
23-
*.heapsnapshot
24-
25-
# coverage
26-
.nyc_output
27-
coverage
28-
29-
# test output
30-
test/**/out*
31-
test/**/next-env.d.ts
2+
dist
323
.DS_Store
33-
/e2e-tests
34-
test/tmp/**
35-
test/.trace
36-
test/traces
37-
38-
# Editors
39-
**/.idea
40-
**/.#*
41-
.nvmrc
42-
43-
# examples
44-
examples/**/out
45-
examples/**/.env*.local
46-
47-
pr-stats.md
48-
test-timings.json
49-
50-
# Vercel
51-
.vercel
52-
.now
53-
54-
# Cache
55-
*.tsbuildinfo
56-
.swc/
57-
.turbo
4+
*.log
5+
coverage

‎.npmignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
src/
2+
tests/
3+
coverage/
4+
*.test.ts
5+
*.test.tsx
6+
tsconfig.json
7+
.eslintrc*
8+
vitest.config.ts

‎LICENSE

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
MIT License
22

3-
Copyright (c) 2024 Jesse McLean
3+
Copyright (c) 2021 SEEK
4+
Copyright (c) 2024 Jesse McLean, Built by Field
45

56
Permission is hereby granted, free of charge, to any person obtaining a copy
67
of this software and associated documentation files (the "Software"), to deal

‎README.md

Lines changed: 110 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,110 @@
1-
# css-utils
2-
1+
# @builtbyfield/css-utils
2+
3+
A collection of type-safe utilities for working with CSS in TypeScript applications.
4+
5+
## Features
6+
7+
- **CSS Variables Utility**: Type-safe creation and manipulation of CSS Custom Properties
8+
- **CSS Calc Utility**: Chainable API for creating CSS `calc()` expressions
9+
- Zero runtime dependencies (except for `cssesc` for proper CSS escaping)
10+
- Comprehensive TypeScript support
11+
- Thoroughly tested utilities
12+
13+
## Installation
14+
15+
```bash
16+
# Using npm
17+
npm install @builtbyfield/css-utils
18+
19+
# Using yarn
20+
yarn add @builtbyfield/css-utils
21+
22+
# Using pnpm
23+
pnpm add @builtbyfield/css-utils
24+
```
25+
26+
## Modules
27+
28+
### CSS Variables Utility
29+
30+
Create and manage CSS Custom Properties with type safety:
31+
32+
```typescript
33+
import { createCSSVar, fallbackCSSVar } from '@builtbyfield/css-utils'
34+
35+
// Simple variable
36+
const bgColor = createCSSVar('background-color')
37+
// Result: var(--background-color)
38+
39+
// With fallback
40+
const textColor = createCSSVar('text-color', { fallback: '#000' })
41+
// Result: var(--text-color, #000)
42+
43+
// Fallback chain
44+
const color = fallbackCSSVar('--primary', '--secondary', '#default')
45+
// Result: var(--primary, var(--secondary, #default))
46+
```
47+
48+
[Read more about CSS Variables Utility](src/vars/README.md)
49+
50+
### CSS Calc Utility
51+
52+
Create complex CSS calculations with a chainable API:
53+
54+
```typescript
55+
import { calc } from '@builtbyfield/css-utils'
56+
57+
// Basic operations
58+
calc.add('100px', '20px') // calc(100px + 20px)
59+
60+
// Chainable operations
61+
calc('100vh')
62+
.subtract('20px')
63+
.multiply(0.5)
64+
.toString() // calc((100vh - 20px) * 0.5)
65+
```
66+
67+
[Read more about CSS Calc Utility](src/calc/README.md)
68+
69+
## Type Safety
70+
71+
The library provides comprehensive TypeScript types for all utilities:
72+
73+
```typescript
74+
import type {
75+
// CSS Variables types
76+
CSSVarDefinition,
77+
CSSVarFunction,
78+
CSSVarName,
79+
CSSVarOptions,
80+
81+
// CSS Calc types
82+
Operator,
83+
Operand,
84+
CalcChain
85+
} from '@builtbyfield/css-utils'
86+
```
87+
88+
## Error Handling
89+
90+
Both utilities include robust error handling:
91+
92+
- Validation of CSS variable names
93+
- Type checking for calc operations
94+
- Descriptive error messages
95+
- Runtime checks for invalid inputs
96+
97+
## Browser Support
98+
99+
This library is designed for modern browsers that support:
100+
- CSS Custom Properties (CSS Variables)
101+
- CSS `calc()` function
102+
103+
## License
104+
105+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
106+
107+
## Acknowledgments
108+
109+
- CSS Calc utility was inspired by [@vanilla-extract/css-utils](https://github.com/vanilla-extract-css/vanilla-extract/tree/master/packages/utils)
110+
- CSS Variables utility was loosely inspired by [vanilla-extract](https://vanilla-extract.style/)'s `vars.ts`

‎eslint.config.mjs

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import pluginJs from "@eslint/js";
2+
import simpleImportSort from "eslint-plugin-simple-import-sort";
3+
import globals from "globals";
4+
import tseslint from "typescript-eslint";
5+
6+
/** @type {import('eslint').Linter.Config[]} */
7+
export default [
8+
{ files: ["**/*.{js,mjs,cjs,ts}"] },
9+
{ languageOptions: { globals: { ...globals.browser, ...globals.node } } },
10+
{
11+
plugins: {
12+
"simple-import-sort": simpleImportSort,
13+
},
14+
},
15+
{
16+
rules: {
17+
"simple-import-sort/imports": "warn",
18+
"simple-import-sort/exports": "warn",
19+
},
20+
},
21+
pluginJs.configs.recommended,
22+
...tseslint.configs.recommended,
23+
];

‎package.json

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,66 @@
11
{
2-
"name": "css-utils",
2+
"name": "@builtbyfield/css-utils",
33
"version": "0.0.1",
4-
"description": "",
5-
"main": "index.js",
4+
"description": "CSS utility functions",
5+
"main": "dist/index.js",
6+
"types": "dist/index.d.ts",
7+
"files": [
8+
"dist"
9+
],
610
"scripts": {
7-
"test": "echo \"Error: no test specified\" && exit 1"
11+
"build": "tsup",
12+
"dev": "tsup --watch",
13+
"typecheck": "tsc --noEmit",
14+
"test": "vitest run",
15+
"test:watch": "vitest",
16+
"test:coverage": "vitest run --coverage",
17+
"test:manual": "vite",
18+
"prepublishOnly": "npm run build",
19+
"prepare": "npm run build"
820
},
9-
"keywords": [],
21+
"dependencies": {
22+
"cssesc": "^3.0.0"
23+
},
24+
"devDependencies": {
25+
"@eslint/js": "^9.15.0",
26+
"@testing-library/dom": "^10.4.0",
27+
"@testing-library/react": "^16.0.1",
28+
"@types/cssesc": "^3.0.2",
29+
"@types/node": "^22.9.3",
30+
"@types/react": "^18.3.12",
31+
"@types/react-dom": "^18.3.1",
32+
"@vitest/coverage-v8": "latest",
33+
"eslint": "^9.15.0",
34+
"eslint-plugin-simple-import-sort": "^12.1.1",
35+
"globals": "^15.12.0",
36+
"happy-dom": "^15.11.6",
37+
"react": "^18.3.1",
38+
"react-dom": "^18.3.1",
39+
"tsup": "^8.3.5",
40+
"typescript": "^5.7.2",
41+
"typescript-eslint": "^8.15.0",
42+
"vite": "^5.4.11",
43+
"vitest": "latest"
44+
},
45+
"keywords": [
46+
"css",
47+
"typescript",
48+
"calc",
49+
"vars",
50+
"custom properties"
51+
],
1052
"author": {
1153
"name": "Jesse McLean",
1254
"email": "[email protected]",
1355
"url": "https://builtbyfield.com"
1456
},
15-
"license": "MIT"
57+
"license": "MIT",
58+
"repository": {
59+
"type": "git",
60+
"url": "git+https://github.com/builtbyfield/css-utils.git"
61+
},
62+
"bugs": {
63+
"url": "https://github.com/builtbyfield/css-utils/issues"
64+
},
65+
"homepage": "https://github.com/builtbyfield/css-utils"
1666
}

0 commit comments

Comments
 (0)