baseline-kit 2.0.0

package/dist/utils/normalize.d.ts

@@ -0,0 +1,65 @@
+export interface NormalizationOptions {
+    /** Base unit for normalization */
+    base?: number;
+    /** Whether to round to nearest base multiple */
+    round?: boolean;
+    /** Optional value clamping */
+    clamp?: {
+        min?: number;
+        max?: number;
+    };
+    /** Suppress warning messages */
+    suppressWarnings?: boolean;
+}
+/**
+ * Normalizes CSS values to a consistent format based on base unit.
+ *
+ * @remarks
+ * Handles:
+ * - CSS length values
+ * - Numeric values
+ * - Special values (auto)
+ * - Rounding to base unit
+ * - Value clamping
+ *
+ * @param value - Value to normalize
+ * @param options - Normalization configuration
+ * @returns Normalized numeric value
+ *
+ * @example
+ * ```ts
+ * // Base unit normalization
+ * normalizeValue(14, { base: 8 })  // => 16
+ *
+ * // With clamping
+ * normalizeValue(14, {
+ *   base: 8,
+ *   clamp: { min: 8, max: 24 }
+ * }) // => 16
+ *
+ * // Without rounding
+ * normalizeValue(14, {
+ *   base: 8,
+ *   round: false
+ * }) // => 14
+ * ```
+ */
+export declare function normalizeValue(value: string | number | undefined, options?: NormalizationOptions): number;
+/**
+ * Normalizes a pair of CSS values.
+ *
+ * @param values - Tuple of values to normalize
+ * @param defaults - Default values if input is undefined
+ * @param options - Normalization options
+ * @returns Tuple of normalized values
+ *
+ * @example
+ * ```ts
+ * normalizeValuePair(
+ *   ['14px', '20px'],
+ *   [0, 0],
+ *   { base: 8 }
+ * ) // => [16, 24]
+ * ```
+ */
+export declare function normalizeValuePair(values: [string | number | undefined, string | number | undefined] | undefined, defaults: [number, number], options?: NormalizationOptions): [number, number];

package/dist/utils/padding.d.ts

@@ -0,0 +1,11 @@
+import { Padding, SpacingProps } from '@components';
+/**
+ * Extract numeric top, right, bottom, left (in px) from `padding` or `block/inline`.
+ * @param spacing - The props which may include padding, block, inline
+ * @returns { top, right, bottom, left } with 0 defaults
+ *
+ * Priority (if padding is defined, it overrides block/inline):
+ * - If `padding` is present, parse it fully (4 edges).
+ * - Otherwise, parse `block` for top/bottom and `inline` for left/right.
+ */
+export declare function parsePadding(spacing: SpacingProps): Padding;

package/dist/utils/parse.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file parse.ts
+ * @description CSS value parsing utilities
+ * @module utils
+ */
+/**
+ * Parses a CSS unit string into its numeric value and unit.
+ *
+ * @remarks
+ * Handles:
+ * - Integer and decimal values
+ * - All CSS units (px, em, rem, etc.)
+ * - Percentage values
+ * - Sign prefixes (+ and -)
+ *
+ * @param value - CSS value string to parse
+ * @returns Object with value and unit, or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * parseUnit('100px')    // => { value: 100, unit: 'px' }
+ * parseUnit('1.5rem')   // => { value: 1.5, unit: 'rem' }
+ * parseUnit('-20%')     // => { value: -20, unit: '%' }
+ * parseUnit('invalid')  // => null
+ * ```
+ */
+export declare function parseUnit(value: string): {
+    value: number;
+    unit: string;
+} | null;
+/**
+ * Formats a value as a valid CSS string.
+ *
+ * @remarks
+ * Handles:
+ * - Numbers (adds px suffix)
+ * - Special values (auto, 100%, etc.)
+ * - Undefined values with defaults
+ *
+ * @param value - Value to format
+ * @param defaultValue - Optional default if value is undefined
+ * @returns Formatted CSS string
+ *
+ * @example
+ * ```ts
+ * formatValue(14)             // => "14px"
+ * formatValue('auto')         // => "auto"
+ * formatValue(undefined, 10)  // => "10px"
+ * formatValue('1fr')         // => "1fr"
+ * ```
+ */
+export declare function formatValue(value: string | number | undefined, defaultValue?: number): string;

package/dist/utils/snapping.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file snapping.ts
+ * @description Baseline grid snapping utilities
+ * @module utils
+ */
+import { SnappingMode, Padding, PaddingValue } from '@components';
+/**
+ * Calculates spacing adjustments to maintain baseline grid alignment.
+ *
+ * @remarks
+ * Provides different snapping behaviors:
+ * - none: No adjustments
+ * - height: Adjusts bottom padding only
+ * - clamp: Adjusts both top and bottom padding
+ *
+ * @param height - Measured element height
+ * @param base - Grid base unit
+ * @param initial - Initial spacing values
+ * @param snapping - Snapping mode to apply
+ * @returns Adjusted spacing values
+ *
+ * @example
+ * ```ts
+ * // Height snapping mode
+ * calculateSnappedSpacing(46, 8, { top: 10, bottom: 10 }, 'height')
+ * // => { top: 10, right: 0, bottom: 12, left: 0 }
+ *
+ * // Clamp mode
+ * calculateSnappedSpacing(45, 8, { top: 10, bottom: 6 }, 'clamp')
+ * // => { top: 2, right: 0, bottom: 1, left: 0 }
+ * ```
+ */
+export declare function calculateSnappedSpacing(height: number, base: number, initial: PaddingValue, snapping: SnappingMode): Padding;

package/dist/utils/timing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file timing.ts
+ * @description Performance optimization utilities
+ * @module utils
+ */
+/**
+ * Creates a debounced version of a function.
+ *
+ * @remarks
+ * Useful for:
+ * - Handling rapid event sequences
+ * - Limiting API calls
+ * - Performance optimization
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ *
+ * @example
+ * ```ts
+ * const handleResize = debounce(() => {
+ *   // Expensive calculation
+ * }, 100);
+ *
+ * window.addEventListener('resize', handleResize);
+ * ```
+ */
+export declare const debounce: <T extends (...args: unknown[]) => void>(fn: T, delay: number) => T;
+/**
+ * Creates a requestAnimationFrame-based throttled function.
+ *
+ * @remarks
+ * Optimizes performance by:
+ * - Limiting execution to animation frames
+ * - Preventing rapid-fire calls
+ * - Maintaining visual smoothness
+ *
+ * @param fn - Function to throttle
+ * @returns RAF-throttled function
+ *
+ * @example
+ * ```ts
+ * const updateScroll = rafThrottle(() => {
+ *   // Update scroll position
+ * });
+ *
+ * document.addEventListener('scroll', updateScroll);
+ * ```
+ */
+export declare const rafThrottle: <T extends (...args: unknown[]) => void>(fn: T) => T;

package/package.json

@@ -0,0 +1,113 @@
+{
+  "scripts": {
+    "lint": "eslint src/lib --fix",
+    "build:type": "tsc -p tsconfig.build.json",
+    "prepare": "bun run build && bun run build:type",
+    "version": "changeset version",
+    "test:coverage": "vitest run --coverage",
+    "release": "changeset publish",
+    "typecheck": "tsc --noEmit",
+    "test:ui": "vitest --ui",
+    "dev": "vite",
+    "test:ci": "vitest run",
+    "format": "prettier --write \"src/lib/**/*.{ts,tsx,css}\"",
+    "prepublishOnly": "bun run build && bun run build:type",
+    "changeset": "changeset",
+    "test": "vitest",
+    "build": "vite build"
+  },
+  "peerDependencies": {
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "main": "dist/index.cjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "react",
+    "grid",
+    "layout",
+    "typescript",
+    "baseline",
+    "guide",
+    "box",
+    "layout",
+    "typography",
+    "spacing",
+    "stack",
+    "padding",
+    "debug",
+    "dev-tool",
+    "pixel-perfect",
+    "vertical-rhythm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dnvt/baseline-kit.git"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.12",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@vitejs/plugin-react-swc": "^3.7.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "autoprefixer": "^10.4.20",
+    "cssnano": "^7.0.6",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.4.2",
+    "rollup": "^4.34.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-visualizer": "^5.14.0",
+    "vite": "^6.1.0",
+    "vite-plugin-static-copy": "^2.2.0",
+    "vitest": "^2.1.8"
+  },
+  "name": "baseline-kit",
+  "version": "2.0.0",
+  "type": "module",
+  "homepage": "https://github.com/dnvt/baseline-kit#readme",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "style": "dist/styles.css",
+  "sideEffects": [
+    "dist/styles.css"
+  ],
+  "bugs": {
+    "url": "https://github.com/dnvt/baseline-kit/issues"
+  },
+  "license": "MIT",
+  "module": "dist/index.mjs",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Francois Denavaut",
+  "description": "Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React applications. It provides configurable overlays for both column-based and baseline grids, flexible spacing components, and theme-aware configuration—all optimized for performance and built with TypeScript.",
+  "dependencies": {
+    "esbuild": "^0.24.2",
+    "postcss-preset-env": "^10.1.3"
+  }
+}