b_short

b_short

Lightning-fast CSS shorthand expansion to longhand properties

Why b_short?

• 📦 Tiny: ~68KB minified + brotli (ESM), ~73KB (CJS) with all dependencies
• ⚡ Fast: Optimized TypeScript with smart caching
• 🎯 Complete: 35+ CSS shorthands including modern features
• 🔒 Type-Safe: Full TypeScript support
• ✅ Tested: 922 tests ensuring 100% accuracy
• 🎨 Flexible: CSS strings or JS objects (camelCase for React)
• 🔄 Bidirectional: Both expand and collapse APIs

Quick Start

npm install b_short

import { expand, collapse } from 'b_short';

// Expand: shorthand → longhand
expand('margin: 10px 20px');
// → "margin-top: 10px;\nmargin-right: 20px;\nmargin-bottom: 10px;\nmargin-left: 20px;"

// Collapse: longhand → shorthand
collapse(`
  margin-top: 10px;
  margin-right: 20px;
  margin-bottom: 10px;
  margin-left: 20px;
`);
// → { ok: true, result: { margin: '10px 20px' }, issues: [] }

collapse({ 'margin-top': '10px', 'margin-right': '10px', 'margin-bottom': '10px', 'margin-left': '10px' });
// → { ok: true, result: { margin: '10px' }, issues: [] }

// JavaScript format (camelCase for React/styled-components)
expand('background: red url(img.png)', { format: 'js' });
// → {
//   backgroundImage: 'url(img.png)',
//   backgroundColor: 'red',
//   backgroundPosition: '0% 0%',
//   ...
// }

API

expand(css, options?)

Expand CSS shorthand properties to longhand equivalents.

import * as b from 'b_short';

const result = b.expand('background: red', {
  format: b.ExpandOptions.Format.CSS,              // 'css' | 'js'
  indent: b.ExpandOptions.Indent.TWO_SPACES,       // 0 | 2 | 4 | 8
  separator: b.ExpandOptions.Separator.NEWLINE,    // '\n' | ' ' | '; ' | ''
  propertyGrouping: b.ExpandOptions.PropertyGrouping.BY_PROPERTY  // 'by-property' | 'by-side'
});

Default Options

import { expand, DEFAULT_EXPAND_OPTIONS } from 'b_short';

const customOptions = {
  ...DEFAULT_EXPAND_OPTIONS,
  indent: 2,
  format: 'js'
};

collapse(properties, options?)

Collapse longhand properties to shorthand equivalents.

import { collapse } from 'b_short';

// Object input
collapse({ 'overflow-x': 'hidden', 'overflow-y': 'auto' });
// → { ok: true, result: { overflow: 'hidden auto' }, issues: [] }

// CSS string input
collapse('overflow-x: hidden;\noverflow-y: auto;', { indent: 2 });
// → { ok: true, result: "  overflow: hidden auto;", issues: [] }

Options:

• indent (number): Indentation level for CSS string output (default: 0)

Result Format

interface ExpandResult {
  ok: boolean;                    // true if no syntax errors
  result?: string | object;       // expanded CSS or undefined if invalid
  issues: Array<Error | Warning>; // syntax errors and warnings
}

interface CollapseResult {
  ok: boolean;                    // true (always succeeds)
  result: string | object;        // collapsed CSS or properties object
  issues: Array<Warning>;         // warnings for incomplete longhands
}

Supported Shorthands (35+)

Box Model & Layout

margin • padding • border • border-width • border-style • border-color • border-top/right/bottom/left • border-radius • inset • overflow

Visual

background (multi-layer) • mask (multi-layer) • outline • text-decoration • text-emphasis

Layout Systems

flex • flex-flow • grid • grid-area • grid-column • grid-row • place-content • place-items • place-self • columns • column-rule

Animation & Motion

animation (multi-layer) • transition (multi-layer) • offset (motion path) • contain-intrinsic-size

Typography

font • list-style

Use Cases

CSS-in-JS Libraries - Perfect for styled-components, emotion, etc.

const styles = expand('margin: 1rem; padding: 0.5rem;', { format: 'js' });

Build Tools - PostCSS plugins, webpack loaders, vite plugins

const normalized = expand(rawCSS, { format: 'css' });

Static Analysis - Linting, optimization, documentation

const { result } = expand(css, { format: 'js' });
const properties = Object.keys(result);

React Inline Styles - Direct camelCase output

const { result } = expand('margin: 1rem', { format: 'js' });
return <div style={result}>Content</div>;

Advanced Features

Multiple Declarations

Both expand and collapse support processing multiple CSS declarations at once.

// Expand multiple shorthands
expand('margin: 10px; padding: 20px; border: 1px solid red');

// Collapse multiple longhands
collapse({
  'margin-top': '10px',
  'margin-right': '10px',
  'margin-bottom': '10px',
  'margin-left': '10px',
  'padding-top': '20px',
  'padding-right': '20px',
  'padding-bottom': '20px',
  'padding-left': '20px'
});
// → { ok: true, result: { margin: '10px', padding: '20px' }, issues: [] }

Multi-layer Support

expand('background: url(1.png), url(2.png) repeat-x');
// Correctly handles multiple background layers

Property Grouping

// by-property (default): CSS spec order
expand('border: 1px solid red; margin: 10px', {
  propertyGrouping: 'by-property'
});

// by-side: Directional grouping
expand('border: 1px solid red; margin: 10px', {
  propertyGrouping: 'by-side'
});

Error Handling

const result = expand('margin: invalid');
if (!result.ok) {
  console.log(result.issues); // Detailed error messages with line numbers
}

Performance

• Fast: Optimized for performance with LRU caching
• Small: 89KB unminified, ~68KB minified + brotli (ESM)
• Efficient: Handles 922 test cases in <2 seconds

TypeScript Support

Full type definitions included:

import type {
  ExpandOptions,
  ExpandResult,
  Format,
  PropertyGrouping
} from 'b_short';

Development

pnpm install      # Install dependencies
pnpm test         # Run tests
pnpm build        # Build for production
pnpm lint         # Lint code

Contributing

Contributions welcome! See CONTRIBUTING.md

License

MIT © alphabio

Acknowledgments

• TypeScript
• @eslint/css-tree - CSS parsing
• b_values - CSS value expansion and validation
• Vitest - Testing
• Biome - Code quality

⭐ Star on GitHub • 📖 Docs • 🐛 Issues

⚡ alphabio