css-calipers 0.9.3 → 0.9.4

package/dist/examples/src/units/viewport-dynamic.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mDvmax = exports.mDvmin = exports.mDvb = exports.mDvi = exports.mDvh = exports.mDvw = void 0;
+const core_1 = require("../core");
+exports.mDvw = (0, core_1.makeUnitHelperFromDefinition)('mDvw');
+exports.mDvh = (0, core_1.makeUnitHelperFromDefinition)('mDvh');
+exports.mDvi = (0, core_1.makeUnitHelperFromDefinition)('mDvi');
+exports.mDvb = (0, core_1.makeUnitHelperFromDefinition)('mDvb');
+exports.mDvmin = (0, core_1.makeUnitHelperFromDefinition)('mDvmin');
+exports.mDvmax = (0, core_1.makeUnitHelperFromDefinition)('mDvmax');

package/dist/examples/src/units/viewport-large.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mLvmax = exports.mLvmin = exports.mLvb = exports.mLvi = exports.mLvh = exports.mLvw = void 0;
+const core_1 = require("../core");
+exports.mLvw = (0, core_1.makeUnitHelperFromDefinition)('mLvw');
+exports.mLvh = (0, core_1.makeUnitHelperFromDefinition)('mLvh');
+exports.mLvi = (0, core_1.makeUnitHelperFromDefinition)('mLvi');
+exports.mLvb = (0, core_1.makeUnitHelperFromDefinition)('mLvb');
+exports.mLvmin = (0, core_1.makeUnitHelperFromDefinition)('mLvmin');
+exports.mLvmax = (0, core_1.makeUnitHelperFromDefinition)('mLvmax');

package/dist/examples/src/units/viewport-small.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mSvmax = exports.mSvmin = exports.mSvb = exports.mSvi = exports.mSvh = exports.mSvw = void 0;
+const core_1 = require("../core");
+exports.mSvw = (0, core_1.makeUnitHelperFromDefinition)('mSvw');
+exports.mSvh = (0, core_1.makeUnitHelperFromDefinition)('mSvh');
+exports.mSvi = (0, core_1.makeUnitHelperFromDefinition)('mSvi');
+exports.mSvb = (0, core_1.makeUnitHelperFromDefinition)('mSvb');
+exports.mSvmin = (0, core_1.makeUnitHelperFromDefinition)('mSvmin');
+exports.mSvmax = (0, core_1.makeUnitHelperFromDefinition)('mSvmax');

package/dist/examples/src/units/viewport.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mVmax = exports.mVmin = exports.mVb = exports.mVi = exports.mVh = exports.mVw = void 0;
+const core_1 = require("../core");
+exports.mVw = (0, core_1.makeUnitHelperFromDefinition)('mVw');
+exports.mVh = (0, core_1.makeUnitHelperFromDefinition)('mVh');
+exports.mVi = (0, core_1.makeUnitHelperFromDefinition)('mVi');
+exports.mVb = (0, core_1.makeUnitHelperFromDefinition)('mVb');
+exports.mVmin = (0, core_1.makeUnitHelperFromDefinition)('mVmin');
+exports.mVmax = (0, core_1.makeUnitHelperFromDefinition)('mVmax');

package/dist/examples/src/validation.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toValidationResult = exports.normalizeValidationResult = void 0;
+const normalizeValidationResult = (result) => {
+    if (result === undefined || result === null)
+        return { valid: true };
+    if (typeof result === "boolean")
+        return { valid: result };
+    if (typeof result === "string") {
+        return result ? { valid: false, message: result } : { valid: true };
+    }
+    return result;
+};
+exports.normalizeValidationResult = normalizeValidationResult;
+const toValidationResult = (error, fallback) => {
+    if (error instanceof Error && error.message)
+        return error.message;
+    return fallback;
+};
+exports.toValidationResult = toValidationResult;

package/dist/examples/validation-and-runtime-checks.example.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Example-only file.
+ *
+ * Not part of the public API surface or published bundle. This sketch shows
+ * how css-calipers can participate in dev-only validation around design
+ * tokens or configuration values inside style helpers or components. The
+ * helpers here are framework-agnostic; imagine them being called from React,
+ * a template system, or a Node script.
+ *
+ * The same `bodyLineHeight` token is used in two different places:
+ * - an icon + label row that returns a small HTML snippet and enforces
+ *   "icon must not exceed line-height"
+ * - a table-of-contents heading row that returns a style object and enforces
+ *   row height and body line-height invariants for readability
+ *
+ * See the sibling unit test example for how to assert related invariants in a unit test.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTocHeadingStyles = exports.renderIconWithLabelHtml = void 0;
+const css_calipers_1 = require("css-calipers");
+// Pretend these tokens come from a design token file or configuration layer.
+// Two different components will enforce different invariants against the same
+// underlying line-height measurement.
+const bodyLineHeight = (0, css_calipers_1.m)(1.4, "rem");
+const iconTokenSize = (0, css_calipers_1.m)(1.2, "rem");
+const tocHeadingRowHeightToken = (0, css_calipers_1.m)(2, "rem");
+// An icon+label row where you don't want the icon to visually dominate the
+// text. In development, assert that the icon's size does not exceed the
+// line-height it sits next to. Here we return a small HTML snippet to
+// illustrate string-based consumers.
+const renderIconWithLabelHtml = (labelText) => {
+    const iconSize = iconTokenSize;
+    if (process.env.NODE_ENV !== "production") {
+        // Make sure both measurements use the same unit family before comparing.
+        (0, css_calipers_1.assertMatchingUnits)(iconSize, bodyLineHeight, "iconWithLabel: icon and line-height units must match");
+        if (iconSize.getValue() > bodyLineHeight.getValue()) {
+            throw new Error(`iconWithLabel: icon must not exceed line-height; ` +
+                `iconSize=${iconSize.css()}, bodyLineHeight=${bodyLineHeight.css()}`);
+        }
+    }
+    const iconStyle = `width:${iconSize.css()};height:${iconSize.css()};`;
+    const labelStyle = `line-height:${bodyLineHeight.css()};`;
+    return `
+    <span class="row">
+      <span class="icon" style="${iconStyle}"/>
+      <span class="label" style="${labelStyle}">${labelText}</span>
+    </span>`;
+};
+exports.renderIconWithLabelHtml = renderIconWithLabelHtml;
+// A table-of-contents row where H2 entries should remain readable and aligned
+// with the typography system. In development, enforce a minimum line-height
+// and require that the H2 row height is at least the underlying line-height.
+const buildTocHeadingStyles = () => {
+    const tocHeadingRowHeight = tocHeadingRowHeightToken;
+    if (process.env.NODE_ENV !== "production") {
+        // Require body line-height to stay within a reasonable range for body
+        // text, using the same measurement token.
+        const minBodyLineHeight = (0, css_calipers_1.m)(1.2, "rem");
+        const maxBodyLineHeight = (0, css_calipers_1.m)(1.8, "rem");
+        const bodyValue = bodyLineHeight.getValue();
+        if (!(bodyValue >= minBodyLineHeight.getValue() &&
+            bodyValue <= maxBodyLineHeight.getValue())) {
+            throw new Error(`tocHeading: body line-height out of range; ` +
+                `${bodyLineHeight.css()} (expected between ` +
+                `${minBodyLineHeight.css()} and ${maxBodyLineHeight.css()})`);
+        }
+        // Row height should not be smaller than the line-height it uses.
+        (0, css_calipers_1.assertMatchingUnits)(tocHeadingRowHeight, bodyLineHeight, "tocHeading: row height and line-height units must match");
+        if (tocHeadingRowHeight.getValue() < bodyLineHeight.getValue()) {
+            throw new Error(`tocHeading: row height must be >= line-height; ` +
+                `row=${tocHeadingRowHeight.css()}, bodyLineHeight=${bodyLineHeight.css()}`);
+        }
+    }
+    // In real code these would be component or style objects. Here we just show
+    // that measurement values flow through `.css()` into plain style shapes.
+    return {
+        row: {
+            minHeight: tocHeadingRowHeight.css(),
+            lineHeight: bodyLineHeight.css(),
+        },
+    };
+};
+exports.buildTocHeadingStyles = buildTocHeadingStyles;

package/dist/examples/validation-unit-tests.example.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Example-only file.
+ *
+ * Not part of the public API surface or published bundle. This sketch shows
+ * how to exercise a simple design-token invariant in unit tests using Vitest,
+ * which this repo already uses for its own test suite. The pattern is test-
+ * runner agnostic; you can adapt it to Jest, Mocha, or any other framework.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const css_calipers_1 = require("css-calipers");
+// Pretend these spacing tokens come from a design token file or configuration
+// layer. The intent is a simple invariant: small <= large and both share units.
+const spacingTokens = {
+    spaceSm: (0, css_calipers_1.m)(4), // defaults to "px" if no unit is given
+    spaceLg: (0, css_calipers_1.m)(12),
+};
+(0, vitest_1.describe)("spacing tokens (example unit test)", () => {
+    (0, vitest_1.it)("use the same unit for related tokens", () => {
+        const { spaceSm, spaceLg } = spacingTokens;
+        // Unit consistency between related tokens.
+        (0, css_calipers_1.assertMatchingUnits)(spaceSm, spaceLg, "spacing tokens: spaceSm and spaceLg must share units");
+    });
+    (0, vitest_1.it)("keep small <= large", () => {
+        const { spaceSm, spaceLg } = spacingTokens;
+        // Ordering invariant: small should never exceed large.
+        const smValue = spaceSm.getValue();
+        const lgValue = spaceLg.getValue();
+        if (!(smValue <= lgValue)) {
+            throw new Error(`spacing tokens out of order: ` +
+                `spaceSm=${spaceSm.css()}, spaceLg=${spaceLg.css()}`);
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-calipers",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Compile-time unit safety for numeric, unit-bearing CSS values via typed measurements.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,11 @@
       "import": "./dist/esm/mediaQueries/index.js",
       "require": "./dist/cjs/mediaQueries/index.js"
     },
+    "./factory": {
+      "types": "./dist/esm/factory.d.ts",
+      "import": "./dist/esm/factory.js",
+      "require": "./dist/cjs/factory.js"
+    },
     "./units": {
       "types": "./dist/esm/units/index.d.ts",
       "import": "./dist/esm/units/index.js",
@@ -74,15 +79,16 @@
     "vitest": "^4.0.14"
   },
   "scripts": {
-    "build": "npm run build:cjs && npm run build:esm",
+    "build": "npm run build:cjs && npm run build:esm && npm run build:examples",
     "build:cjs": "echo \"🛠️  Building CommonJS (cjs) bundle...\" && tsc -p tsconfig.build.cjs.json",
     "build:esm": "echo \"🛠️  Building ES module (esm) bundle...\" && tsc -p tsconfig.build.esm.json && node scripts/emit-esm-package.mjs",
+    "build:examples": "tsc -p tsconfig.examples.json --noEmit",
     "build:test": "npm run build && npm run test",
     "build:delete": "node -e \"const { existsSync, rmSync } = require('fs'); const paths = ['dist/cjs', 'dist/esm']; for (const p of paths) { console.log('Scanning', p + '...'); if (existsSync(p)) { console.log('Found', p + ', deleting...'); rmSync(p, { recursive: true, force: true }); console.log('Deleted', p); } else { console.log(p + ' not found, skipping.'); } }\"",
-    "prepublishOnly": "node -e \"if (!process.env.CSS_CALIPERS_RELEASE) { console.error('Direct npm publish is disabled; use \\\"npm run release\\\" instead.'); process.exit(1); }\"",
+    "prepublishOnly": "node -e \"if (!process.env.CSS_CALIPERS_RELEASE) { console.error('Direct npm publish is disabled; use \\\"npm run release\\\" instead.'); process.exit(1); }\" && npm run test:internal",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",
-    "test": "npm run test:core && npm run test:mediaQueries && npm run test:dist && npm run test:types && npm run test:tsc && npm run lint",
+    "test": "npm run build && npm run test:core && npm run test:mediaQueries && npm run test:factory && npm run test:dist && npm run test:types && npm run test:tsc && npm run lint && npm run test:internal",
     "test:mediaQueries": "vitest run tests/runtime/mediaQueries/mediaQueries.src.test.ts",
     "test:mediaQueries:cjs": "vitest run tests/runtime/mediaQueries/mediaQueries.cjs.test.ts tests/runtime/api-surface/mediaQueries.api-surface.cjs.test.ts",
     "test:mediaQueries:esm": "vitest run tests/runtime/mediaQueries/mediaQueries.esm.test.ts tests/runtime/api-surface/mediaQueries.api-surface.esm.test.ts",
@@ -95,6 +101,11 @@
     "test:lint": "npm run lint",
     "test:types": "echo \"\n 🧪 Starting tsd type checks...\n\" && tsd --files tests/types/**/*.test-d.ts && echo \"✅ tsd type checks passed!\n\"",
     "test:tsc": "tsc -p tsconfig.json --noEmit",
-    "test:dist": "npm run build && npm run test:core:dist && npm run test:mediaQueries:dist"
+    "test:dist": "npm run test:core:dist && npm run test:mediaQueries:dist && npm run test:factory:dist",
+    "test:factory": "vitest run tests/runtime/factory/factory.src.test.ts",
+    "test:factory:cjs": "vitest run tests/runtime/factory/factory.cjs.test.ts tests/runtime/api-surface/factory.api-surface.cjs.test.ts",
+    "test:factory:esm": "vitest run tests/runtime/factory/factory.esm.test.ts tests/runtime/api-surface/factory.api-surface.esm.test.ts",
+    "test:factory:dist": "npm run test:factory:cjs && npm run test:factory:esm",
+    "test:internal": "tsc -p tsconfig.internal.json --noEmit"
   }
 }