Layout Mixins

/**
 * Provides clearfix solution for floating elements
 * @param parent - Optional parent selector (default: "&")
 * @returns Styles object with clearfix properties
 */
function clearFix(parent?: string): Styles;

/**
 * Positions an element to cover its parent completely
 * @param offset - Optional offset from edges (default: 0)
 * @returns Styles object for absolute positioning covering parent
 */
function cover(offset?: string): Styles;

/**
 * Creates ellipsis text overflow with optional width constraint
 * @param width - Optional width constraint (default: "100%")
 * @returns Styles object for text ellipsis behavior
 */
function ellipsis(width?: string): Styles;

/**
 * Enables word wrapping for long words and URLs
 * @param wrap - Optional wrap method ("normal" | "break-word" | "break-all")
 * @returns Styles object for word wrapping
 */
function wordWrap(wrap?: string): Styles;

import { clearFix, cover, ellipsis, wordWrap } from "polished";

// Layout utilities
const containerStyles = {
  ...clearFix(),  // Clear floated children
  position: "relative"
};

const overlayStyles = {
  ...cover("10px"),  // Cover parent with 10px offset
  backgroundColor: "rgba(0,0,0,0.5)"
};

const titleStyles = {
  ...ellipsis("200px"),  // Truncate with ellipsis at 200px
  fontWeight: "bold"
};

const linkStyles = {
  ...wordWrap("break-word")  // Break long URLs appropriately
};

/**
 * Creates fluid ranges for responsive design with CSS calc()
 * @param cssProp - Configuration object(s) for fluid range properties
 * @param minScreen - Minimum screen size (default: "320px")
 * @param maxScreen - Maximum screen size (default: "1200px")
 * @returns Styles object with fluid range calculations
 */
function fluidRange(
  cssProp: FluidRangeConfiguration | FluidRangeConfiguration[],
  minScreen?: string,
  maxScreen?: string
): Styles;

/**
 * Creates CSS between two screen sizes using media queries
 * @param fromSize - Starting screen size
 * @param toSize - Ending screen size
 * @param cssProp - CSS properties to apply within range
 * @returns Styles object with media query
 */
function between(fromSize: string, toSize: string, cssProp: Styles): Styles;

/**
 * Provides high-DPI (retina) display targeting
 * @param ratio - DPI ratio to target (default: 1.3)
 * @returns Styles object with high-DPI media query
 */
function hiDPI(ratio?: number): Styles;

import { fluidRange, between, hiDPI } from "polished";

// Fluid typography that scales with viewport
const fluidText = {
  ...fluidRange(
    [
      { prop: "fontSize", fromSize: "14px", toSize: "18px" },
      { prop: "lineHeight", fromSize: "1.4", toSize: "1.6" }
    ],
    "320px", "1200px"
  )
};

// Styles only between specific screen sizes
const tabletStyles = {
  ...between("768px", "1024px", {
    fontSize: "16px",
    padding: "20px"
  })
};

// High-resolution display optimizations
const retinaStyles = {
  ...hiDPI(2, {
    backgroundImage: "url('logo@2x.png')",
    backgroundSize: "contain"
  })
};

/**
 * Hides text content while keeping it accessible to screen readers
 * @returns Styles object for accessible text hiding
 */
function hideText(): Styles;

/**
 * Visually hides element while keeping it accessible to screen readers
 * @returns Styles object for accessible element hiding
 */
function hideVisually(): Styles;

/**
 * Provides comprehensive font-face declaration
 * @param fontFamily - Font family name
 * @param fontFilePath - Path to font file (without extension)
 * @param fileFormats - Array of font formats to include
 * @param fontWeight - Font weight (default: "normal")
 * @param fontStyle - Font style (default: "normal")
 * @param fontStretch - Font stretch (default: "normal")
 * @param fontDisplay - Font display strategy (default: "auto")
 * @param fontVariationSettings - Font variation settings
 * @param fontFeatureSettings - Font feature settings
 * @param unicodeRange - Unicode range for font
 * @param fontVariant - Font variant
 * @param fontStretch - Font stretch value
 * @returns Styles object with @font-face declaration
 */
function fontFace(
  fontFamily: string,
  fontFilePath: string,
  fileFormats?: Array<string>,
  fontWeight?: string,
  fontStyle?: string,
  fontStretch?: string,
  fontDisplay?: string,
  fontVariationSettings?: string,
  fontFeatureSettings?: string,
  unicodeRange?: string,
  fontVariant?: string
): Styles;

/**
 * Creates CSS linear gradient
 * @param options - Gradient configuration object
 * @returns Linear gradient CSS value
 */
function linearGradient(options: LinearGradientConfiguration): string;

/**
 * Creates CSS radial gradient
 * @param options - Gradient configuration object
 * @returns Radial gradient CSS value
 */
function radialGradient(options: RadialGradientConfiguration): string;

/**
 * Creates CSS triangle using borders
 * @param options - Triangle configuration object
 * @returns Styles object for triangle shape
 */
function triangle(options: TriangleConfiguration): Styles;

/**
 * Provides retina image background with fallback
 * @param filename - Base filename (without @2x suffix)
 * @param backgroundSize - Background size value
 * @param extension - File extension (default: "png")
 * @param retinaFilename - Optional custom retina filename
 * @param retinaSuffix - Retina filename suffix (default: "@2x")
 * @returns Styles object with retina image handling
 */
function retinaImage(
  filename: string,
  backgroundSize?: string,
  extension?: string,
  retinaFilename?: string,
  retinaSuffix?: string
): Styles;

import { linearGradient, triangle, retinaImage } from "polished";

// Gradient backgrounds
const heroBackground = {
  background: linearGradient({
    colorStops: ["#667eea 0%", "#764ba2 100%"],
    toDirection: "to right"
  })
};

// CSS triangle shapes
const tooltipArrow = {
  ...triangle({
    pointingDirection: "top",
    width: "10px",
    height: "8px",
    foregroundColor: "#333"
  }),
  position: "absolute",
  bottom: "-8px"
};

// Retina image handling
const logoStyles = {
  ...retinaImage("logo", "100px 50px", "png"),
  display: "block",
  width: "100px",
  height: "50px"
};

/**
 * Provides collection of timing functions for animations
 * @returns Object containing various timing function definitions
 */
function timingFunctions(): TimingFunctions;

/**
 * Provides CSS normalization rules
 * @returns Styles object with normalize.css-style rules
 */
function normalize(): Styles;

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

interface FluidRangeConfiguration {
  prop: string;
  fromSize: string;
  toSize: string;
}

interface LinearGradientConfiguration {
  colorStops: Array<string>;
  toDirection?: string;
  fallback?: string;
}

interface RadialGradientConfiguration {
  colorStops: Array<string>;
  extent?: string;
  position?: string;
  shape?: string;
  fallback?: string;
}

interface TriangleConfiguration {
  pointingDirection: "top" | "right" | "bottom" | "left" | 
                     "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
  width: string;
  height: string;
  foregroundColor: string;
  backgroundColor?: string;
}

interface TimingFunctions {
  [key: string]: string;
}