css-calipers 0.12.0 → 0.13.0

package/README.md

@@ -1,18 +1,26 @@
 # CSS-Calipers
 
-**CSS is code. Measure it like one.**  
-Compile-time unit safety for numeric, unit-bearing CSS values, no surprises at runtime.
+[![npm](https://img.shields.io/npm/v/css-calipers.svg)](https://www.npmjs.com/package/css-calipers)
+[![types](https://img.shields.io/npm/types/css-calipers.svg)](https://www.npmjs.com/package/css-calipers)
+[![license](https://img.shields.io/npm/l/css-calipers.svg)](./LICENSE.txt)
 
-CSS-Calipers is a tiny layer for typed CSS measurements. Stop parsing CSS
-strings and concatenating units. Do your math on real numbers, get
-compile-time unit safety, and output CSS only at the edges.
+**CSS is code. Treat it that way.**  
+Compile-time unit safety for numeric, unit-bearing CSS values, with no surprises at runtime.
 
-This README is a general overview. Deeper module guides live in their own files.
-
-Module guides:
+```ts
+// Before: pull the number AND the unit apart, do the math, glue them back
+const match = base.match(/^(-?\d*\.?\d+)([a-z%]+)$/i);
+if (!match) throw new Error(`Bad measurement: ${base}`);
+const [, numStr, unit] = match;
+const num = parseFloat(numStr);
+const pad = `${num + 4}${unit}`;   // and nobody checked that `unit` matches what the caller expects
+
+// After: typed math, units enforced by the compiler
+const base = m(8);                 // or m(8, "rem"), m(1.5, "em"), etc.
+const pad = base.add(4).css();     // type error if units don't match
+```
 
-- Measurements core: README_MEASUREMENT.md
-- Media queries: README_MEDIAQUERIES.md
+A small TypeScript library for **type-safe CSS measurements**. Do arithmetic on real numbers with the unit attached, let the compiler catch `px`-vs-`rem` mistakes, and emit a CSS string only at the edge.
 
 At a glance:
 
@@ -26,15 +34,6 @@ At a glance:
 npm install css-calipers
 ```
 
-### Status & support
-
-> 🚧 Work in progress.  
-> API surface and docs may change between `0.x` releases until the first stable version.
-
-- Status: early `0.x` release. Backwards compatibility is not guaranteed until `1.0.0`.
-- Questions or bugs: open an issue on GitHub (see the repository link at the top of this page or in `package.json`).
-- Tooling: tested primarily with TypeScript 5.6+ on Node 18+.
-
 ---
 
 ## Quick start
@@ -61,6 +60,16 @@ If you prefer, you can also import unit helpers from dedicated subpaths. For exa
 
 ---
 
+## Status & support
+
+> API surface and docs may change between `0.x` releases until the first stable version.
+
+- Status: early `0.x` release. Backwards compatibility is not guaranteed until `1.0.0`.
+- Questions or bugs: open an issue on GitHub (see the repository link at the top of this page or in `package.json`).
+- Tooling: tested primarily with TypeScript 5.6+ on Node 18+.
+
+---
+
 ## Media queries
 
 ```ts
@@ -125,8 +134,8 @@ CSS-Calipers is a good fit if:
 - You already use TypeScript (or plan to) and want compile-time guarantees around CSS units.
 - You have a design system or token layer where layout math and unit conversions matter.
 - You care about catching unit mismatches and layout invariants early, in dev or tests.
-This library is opinionated about types and emitting valid CSS at the edges,
-but intentionally loose about how you structure or apply styles in between.
+  This library is opinionated about types and emitting valid CSS at the edges,
+  but intentionally loose about how you structure or apply styles in between.
 
 It’s probably overkill if:
 
@@ -177,7 +186,7 @@ const columns = 3;
 if (process.env.NODE_ENV !== "production") {
   assertCondition(
     () => columns > 0,
-    "cardGridStyles: columns must be greater than zero"
+    "cardGridStyles: columns must be greater than zero",
   );
 }
 
@@ -218,7 +227,7 @@ if (process.env.NODE_ENV !== "production") {
   assertMatchingUnits(
     formTokens.field.paddingBlock,
     formTokens.field.paddingInline,
-    "Form control padding mismatch"
+    "Form control padding mismatch",
   );
 }
 ```
@@ -268,9 +277,11 @@ css-calipers.m: Non-finite measurement value: undefined [code=CALIPERS_E_NONFINI
 ```
 
 What it means
+
 - A measurement was constructed with undefined, NaN, or Infinity.
 
 How to fix
+
 - Provide a real numeric value and a unit (m(12), m(12, "px")).
 - Add a context label so the error points to the calling helper or token (m(12, { context: "tokens.cardWidth" })).
 
@@ -283,9 +294,11 @@ css-calipers.assertMatchingUnits: measurement unit mismatch: px vs em [code=CALI
 ```
 
 What it means
+
 - You mixed units without an explicit conversion.
 
 How to fix
+
 - Normalize units at the source (convert em to px or vice versa).
 - Add an assertMatchingUnits call where the values enter your system.
 
@@ -298,9 +311,11 @@ css-calipers.Measurement.divide: Cannot divide 10px by zero [code=CALIPERS_E_DIV
 ```
 
 What it means
+
 - You attempted to divide by zero in a measurement operation.
 
 How to fix
+
 - Guard inputs before dividing or replace zero with a safe fallback.
 
 ### Clamp bounds
@@ -312,9 +327,11 @@ css-calipers.Measurement.clamp: clamp: min (20px) must be <= max (12px) [code=CA
 ```
 
 What it means
+
 - The clamp minimum is greater than the clamp maximum.
 
 How to fix
+
 - Ensure min and max come from the same source or swap them before calling clamp.
 
 ### Stack hints and configuration
@@ -456,6 +473,13 @@ by your styling layer. That’s the intended scope: CSS will always be a mix of
 values, but the library gives you a tight, unit-safe boundary for the numeric
 parts inside a broader styling solution.
 
+### Module guides
+
+Deeper guides live alongside this README:
+
+- Measurements core: [README_MEASUREMENT.md](README_MEASUREMENT.md)
+- Media queries: [README_MEDIAQUERIES.md](README_MEDIAQUERIES.md)
+
 ### Further examples in this repo
 
 The `examples/` folder contains a few non-published usage sketches:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-calipers",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Compile-time unit safety for numeric, unit-bearing CSS values via typed measurements.",
   "license": "MIT",
   "repository": {