Helper Functions

/**
 * Converts pixel values to rem units based on a context
 * @param pxval - Pixel value as string or number
 * @param base - Base font size in pixels (default: 16px)
 * @returns Converted rem value as string
 */
function rem(pxval: string | number, base?: string | number): string;

/**
 * Converts pixel values to em units based on a context
 * @param pxval - Pixel value as string or number
 * @param base - Base font size in pixels (default: 16px)
 * @returns Converted em value as string
 */
function em(pxval: string | number, base?: string | number): string;

/**
 * Converts rem values to pixel values
 * @param remval - Rem value as string or number
 * @param base - Base font size in pixels (default: 16px)
 * @returns Converted pixel value as string
 */
function remToPx(remval: string | number, base?: string | number): string;

/**
 * Strips the unit from a value, returning just the number
 * @param value - CSS value with unit (e.g., "16px", "1.5rem")
 * @returns Numeric value without unit
 */
function stripUnit(value: string): number;

/**
 * Parses a CSS value and returns an array containing the numeric value and unit
 * @param value - CSS value string (e.g., "16px", "1.5rem")
 * @returns Tuple of [number, unit] where unit may be undefined for unitless values
 */
function getValueAndUnit(value: string): [number, string | undefined];

import { rem, em, stripUnit, getValueAndUnit } from "polished";

// Unit conversions
const fontSize = rem("16px");        // "1rem"
const margin = em("24px", "18px");   // "1.33333em" (24px in context of 18px base)

// Value parsing
const numericValue = stripUnit("16px");           // 16
const [value, unit] = getValueAndUnit("1.5rem"); // [1.5, "rem"]

/**
 * Fetches the value of a CSS variable in the :root scope, or returns a default value
 * @param cssVariable - CSS variable name (with or without -- prefix)
 * @param defaultValue - Default value if CSS variable is not found
 * @returns CSS variable value or default value
 */
function cssVar(cssVariable: string, defaultValue?: string | number): string | number;

/**
 * Maps values to directional CSS properties (top, right, bottom, left)
 * @param property - CSS property name (e.g., "margin", "padding")
 * @param values - 1-4 values following CSS shorthand rules
 * @returns Object with directional property assignments
 */
function directionalProperty(property: string, ...values: Array<?string | ?number>): Styles;

/**
 * Adds !important declaration to a CSS value
 * @param value - CSS value to make important
 * @returns CSS value with !important declaration
 */
function important(value: string | number): string;

import { cssVar, directionalProperty, important } from "polished";

// CSS variables with fallbacks
const primaryColor = cssVar("--primary-color", "#3498db");
const spacing = cssVar("--base-spacing", "16px");

// Directional properties
const margins = directionalProperty("margin", "10px", "20px");
// Returns: { marginTop: "10px", marginRight: "20px", marginBottom: "10px", marginLeft: "20px" }

// Important declarations
const criticalStyle = {
  color: important("#ff0000"),  // "color: #ff0000 !important"
  fontSize: important("18px")   // "font-size: 18px !important"
};

/**
 * Calculates values on a modular scale
 * @param steps - Number of steps up or down the scale (positive or negative integer)
 * @param base - Base value for the scale (default: "1rem")
 * @param ratio - Scale ratio (default: 1.618, golden ratio)
 * @returns Calculated value as string with appropriate unit
 */
function modularScale(steps: number, base?: string | number, ratio?: number): string;

import { modularScale } from "polished";

// Typography scale using golden ratio
const h1Size = modularScale(4);      // Large heading
const h2Size = modularScale(3);      // Medium heading  
const bodySize = modularScale(0);    // Base size (1rem)
const smallSize = modularScale(-1);  // Small text

// Custom base and ratio
const customScale = modularScale(2, "18px", 1.5);  // Custom base and ratio

// Example scale generation
const typeScale = {
  h1: modularScale(4, "16px", 1.25),    // ~2.44rem
  h2: modularScale(3, "16px", 1.25),    // ~1.95rem
  h3: modularScale(2, "16px", 1.25),    // ~1.56rem
  body: modularScale(0, "16px", 1.25),  // 1rem
  small: modularScale(-1, "16px", 1.25) // ~0.8rem
};

interface Styles {
  [key: string]: string | number | Styles;
}