CSX CSS Utilities for TypeStyle

Common errors

• Expected `rgb(0, 0, 0)` but got `rgb(0,0,0)` in CSS output.

  cause Difference in color function string output due to new spacing introduced in v10.0.0 to align with CSSOM.
  fix This is an intended breaking change in output formatting. Adjust any tests or code that performs exact string comparisons on color function outputs to reflect the new spaced format. No functional code change is needed.

• Type error: Argument of type 'string' is not assignable to parameter of type 'CssLength'.

  cause Attempting to pass a raw string where a `csx` unit helper (like `px()`, `em()`) is expected, or providing an invalid value type to a CSX function.
  fix Always use the appropriate CSX helper functions for units and values, e.g., `px(10)` instead of `'10px'`, or `percent(50)` instead of `'50%'`. Ensure types match the function signatures.

• ReferenceError: require is not defined

  cause Attempting to import `csx` using CommonJS `require()` syntax in an environment (e.g., a modern TypeScript project, browser ES module context, or Node.js with type:"module") that expects ES module syntax.
  fix Update your import statements to use ES module syntax: `import { color } from 'csx';`. Ensure your project's `tsconfig.json` (if applicable) and build setup are configured for ES modules (e.g., `"module": "esnext"` or `"nodenext"`).

Warnings

• breaking CSS color functions (e.g., `rgb()`, `hsl()`) now include spaces after commas in their output to match the CSS Object Model (CSSOM). This changes the exact string output of color functions.
  Fix: Update any snapshot tests or assertions that directly compare the string output of CSX color functions. No code change is typically required for runtime behavior unless specific string comparisons are in place.
• breaking The behavior of `background-size` helper was fixed in `v9.0.2` to correctly use `/` between position and size. Code relying on the incorrect pre-`v9.0.2` output will produce different CSS.
  Fix: Verify `background-size` usage. If you were implicitly relying on incorrect output, ensure your code now explicitly passes position and size, e.g., `backgroundSize('center', '50%')` to get `'center / 50%'`.
• gotcha In `v9.0.2`, a more specific type definition was added for `background-size` that throws a type error if `size` is provided but `position` is undefined. This improves type safety but can break existing code that was implicitly passing `undefined` for position.
  Fix: Ensure that when providing a `size` argument to `backgroundSize()`, a valid `position` argument (even if 'initial' or '0 0') is also provided to satisfy the type definition.
• breaking Starting with `v5.0.0`, all styles generated by CSX are vendor prefixed by default and are explicitly meant to be used in conjunction with TypeStyle. Using CSX independently of TypeStyle or in other styling solutions may lead to unexpected behavior or incomplete CSS output.
  Fix: Ensure that CSX is used alongside TypeStyle, as it's designed to complement its functionality. If you need vendor prefixing control, manage it via TypeStyle's configuration.

Install

• npm install csx npm
• yarn add csx yarn
• pnpm add csx pnpm

Imports

• color
  wrong:

  const color = require('csx').color;

  correct:

  import { color } from 'csx'

  CSX is primarily designed for TypeScript and ES module environments. CommonJS `require()` is not officially supported and may lead to issues with type inference or bundling in modern projects.
• rgb
  wrong:

  import rgb from 'csx/lib/rgb'

  correct:

  import { rgb } from 'csx'

  Named exports are the standard for all utility functions. Direct imports from subpaths are discouraged and may break with future updates.
• px
  wrong:

  import { px } from 'csx/dist/units'

  correct:

  import { px } from 'csx'

  All core utilities should be imported directly from the top-level 'csx' package. Importing from internal paths ('dist', 'lib') is unstable and not recommended.
• margin
  wrong:

  import * as csx from 'csx'; const m = csx.margin;

  correct:

  import { margin } from 'csx'

  While `import * as csx` works, it's generally better practice to destructure specific utilities for tree-shaking and clarity, especially with many functions available.

Quickstart

Demonstrates defining various CSS values and shorthands using CSX helpers like colors, units, margins, and then integrating them into a TypeStyle stylesheet.

import { color, rgb, hsl, px, em, rem, percent, viewHeight, viewWidth, margin, padding, url, quote } from 'csx';
import { style } from 'typestyle'; // Assuming TypeStyle is used as recommended

// Define some CSS values using CSX helpers
const brandColor = color('#1E90FF'); // Dodger Blue
const semiTransparent = rgb(30, 144, 255, 0.7); // RGB with alpha
const lightAccent = hsl(200, 80, 95); // HSL color

// Unit helpers
const defaultPadding = px(16);
const headingFontSize = em(2.5);
const bodyFontSize = rem(1.1);
const viewportWidth = viewWidth(100);
const elementHeight = viewHeight(50);
const responsiveWidth = percent(75);

// Shorthand properties
const cardMargin = margin(px(20), 'auto'); // Top/Bottom 20px, Left/Right auto
const elementPadding = padding(defaultPadding, px(10)); // Top/Bottom 16px, Left/Right 10px

// URL and quoting helpers
const backgroundImage = url('/assets/background.jpg');
const fontFaceName = quote('My Custom Font');

// Example of integrating with TypeStyle
const myStyledElement = style({
  color: brandColor.toString(),
  backgroundColor: semiTransparent.toString(),
  border: `${px(1)} solid ${lightAccent.toString()}`,
  padding: elementPadding.toString(),
  margin: cardMargin.toString(),
  width: responsiveWidth.toString(),
  height: elementHeight.toString(),
  fontSize: bodyFontSize.toString(),
  fontFamily: fontFaceName.toString(),
  backgroundImage: backgroundImage.toString(),
  $nest: {
    '& > h1': {
      fontSize: headingFontSize.toString(),
      textAlign: 'center',
    },
    '@media (max-width: 768px)': {
      width: viewportWidth.toString(),
      margin: margin(px(10)),
    },
  },
});

console.log('CSX Brand Color:', brandColor.toString());
console.log('CSX Element Padding:', elementPadding.toString());
console.log('CSX Card Margin:', cardMargin.toString());
console.log('CSX Background Image:', backgroundImage.toString());
console.log('CSX Font Face Name:', fontFaceName.toString());
console.log('Generated TypeStyle class name:', myStyledElement);