Shorthand Properties

/**
 * Generates margin shorthand properties with intelligent value expansion
 * @param values - 1-4 margin values following CSS shorthand rules
 * @returns Styles object with margin properties
 */
function margin(...values: Array<?string | ?number>): Styles;

/**
 * Generates padding shorthand properties with intelligent value expansion
 * @param values - 1-4 padding values following CSS shorthand rules
 * @returns Styles object with padding properties
 */
function padding(...values: Array<?string | ?number>): Styles;

import { margin, padding } from "polished";

// Margin variations
const singleValue = margin("20px");           // All sides: 20px
const twoValues = margin("10px", "20px");     // Vertical: 10px, Horizontal: 20px
const threeValues = margin("10px", "20px", "15px");  // Top: 10px, Horizontal: 20px, Bottom: 15px
const fourValues = margin("10px", "20px", "15px", "25px");  // Top, Right, Bottom, Left

// Padding with mixed units
const mixedPadding = padding("1rem", "20px", "1.5rem");

/**
 * Generates border shorthand properties for specific sides or all sides
 * @param side - Optional side specification ("top", "right", "bottom", "left")
 * @param width - Border width value
 * @param style - Border style value
 * @param color - Border color value
 * @returns Styles object with border properties
 */
function border(side?: string, width?: string, style?: string, color?: string): Styles;

/**
 * Generates border-color shorthand properties
 * @param values - 1-4 color values following CSS shorthand rules
 * @returns Styles object with border-color properties
 */
function borderColor(...values: Array<?string>): Styles;

/**
 * Generates border-radius shorthand properties
 * @param side - Optional corner specification or radius value
 * @param radius - Radius value when side is specified
 * @returns Styles object with border-radius properties
 */
function borderRadius(side?: string, radius?: string): Styles;

/**
 * Generates border-style shorthand properties
 * @param values - 1-4 style values following CSS shorthand rules
 * @returns Styles object with border-style properties
 */
function borderStyle(...values: Array<?string>): Styles;

/**
 * Generates border-width shorthand properties
 * @param values - 1-4 width values following CSS shorthand rules
 * @returns Styles object with border-width properties
 */
function borderWidth(...values: Array<?string | ?number>): Styles;

import { border, borderColor, borderRadius, borderStyle, borderWidth } from "polished";

// Complete border
const cardBorder = {
  ...border("1px", "solid", "#ddd")  // All sides
};

// Specific side border
const topBorder = {
  ...border("top", "2px", "solid", "#333")  // Top border only
};

// Border components
const borderStyles = {
  ...borderWidth("1px", "2px"),           // Top/bottom: 1px, Left/right: 2px
  ...borderStyle("solid", "dashed"),      // Top/bottom: solid, Left/right: dashed
  ...borderColor("#333", "#666", "#999"), // Top: #333, Sides: #666, Bottom: #999
  ...borderRadius("top", "10px")          // Top corners: 10px
};

/**
 * Generates position shorthand properties (top, right, bottom, left)
 * @param values - 1-4 position values following CSS shorthand rules
 * @returns Styles object with position offset properties
 */
function position(...values: Array<?string | ?number>): Styles;

/**
 * Generates size shorthand properties (width and height)
 * @param width - Width value
 * @param height - Height value (defaults to width if not provided)
 * @returns Styles object with width and height properties
 */
function size(width: string | number, height?: string | number): Styles;

import { position, size } from "polished";

// Absolute positioning
const absoluteElement = {
  position: "absolute",
  ...position("10px", "20px", "30px", "40px")  // Top, Right, Bottom, Left
};

// Size variations
const square = size("100px");           // 100px × 100px
const rectangle = size("200px", "150px"); // 200px × 150px
const responsive = size("100%", "50vh");  // Full width, half viewport height

/**
 * Generates background shorthand properties for multiple backgrounds
 * @param backgrounds - Array of background configuration objects
 * @returns Styles object with background properties
 */
function backgrounds(...backgrounds: Array<BackgroundConfiguration>): Styles;

/**
 * Generates background-image shorthand for multiple images
 * @param images - Array of image URLs or gradient functions
 * @returns Styles object with background-image property
 */
function backgroundImages(...images: Array<string>): Styles;

/**
 * Generates animation shorthand properties
 * @param animations - Array of animation configuration objects
 * @returns Styles object with animation properties
 */
function animation(...animations: Array<AnimationConfiguration>): Styles;

/**
 * Generates transition shorthand properties
 * @param transitions - Array of transition configuration objects
 * @returns Styles object with transition properties
 */
function transitions(...transitions: Array<TransitionConfiguration>): Styles;

import { animation, transitions } from "polished";

// Animation definitions
const fadeIn = {
  ...animation({
    name: "fadeIn",
    duration: "0.3s",
    timingFunction: "ease-out",
    fillMode: "forwards"
  })
};

// Multiple transitions
const buttonTransitions = {
  ...transitions(
    { property: "background-color", duration: "0.2s" },
    { property: "transform", duration: "0.1s", timingFunction: "ease-out" }
  )
};

/**
 * Generates selector string for text input elements
 * @param pseudoSelector - Optional pseudo-selector to append
 * @returns Selector string targeting text input elements
 */
function textInputs(pseudoSelector?: string): string;

/**
 * Generates selector string for button elements
 * @param pseudoSelector - Optional pseudo-selector to append
 * @returns Selector string targeting button elements
 */
function buttons(pseudoSelector?: string): string;

import { textInputs, buttons } from "polished";

// Styled components usage
const StyledInput = styled.input`
  ${textInputs()} {
    border: 1px solid #ccc;
    padding: 8px 12px;
    border-radius: 4px;
  }

  ${textInputs(":focus")} {
    border-color: #007bff;
    outline: none;
  }
`;

const StyledButton = styled.button`
  ${buttons()} {
    background: #007bff;
    color: white;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
  }

  ${buttons(":hover")} {
    background: #0056b3;
  }
`;

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

interface BackgroundConfiguration {
  image?: string;
  position?: string;
  size?: string;
  repeat?: string;
  attachment?: string;
  origin?: string;
  clip?: string;
  color?: string;
}

interface AnimationConfiguration {
  name: string;
  duration?: string;
  timingFunction?: string;
  delay?: string;
  iterationCount?: string;
  direction?: string;
  fillMode?: string;
  playState?: string;
}

interface TransitionConfiguration {
  property: string;
  duration?: string;
  timingFunction?: string;
  delay?: string;
}