baseline-kit 3.0.2 → 5.1.0

package/dist/utils/index.d.ts

@@ -1,15 +0,0 @@
-/**
- * @file Utility Exports (utils/index.ts)
- * @description Utility functions for baseline-kit operations
- * @module baseline-kit/utils
- */
-export * from './convert';
-export * from './math';
-export * from './normalize';
-export * from './padding';
-export * from './snapping';
-export * from './grid';
-export * from './merge';
-export * from './parse';
-export * from './timing';
-export * from './ssr';

package/dist/utils/math.d.ts

@@ -1,48 +0,0 @@
-/**
- * Calculates the modulo (remainder) of a CSS value when divided by a base unit.
- *
- * @param value - Input value (number or CSS string)
- * @param base - Base unit to calculate remainder against
- * @param options - Optional calculation controls
- * @returns Remainder in pixel units (e.g., "6px")
- */
-export declare function moduloize(value: number | string | undefined, base: number, options?: {
-    round?: boolean;
-}): string;
-/**
- * Constrains a number within a specified range.
- *
- * @param value - Number to clamp
- * @param min - Minimum allowed value
- * @param max - Maximum allowed value
- * @returns Clamped value
- */
-export declare function clamp(value: number, min: number, max: number): number;
-/**
- * Rounds a number to specified precision.
- *
- * @param value - Number to round
- * @param precision - Decimal places (default: 0)
- * @returns Rounded number
- */
-export declare function round(value: number, precision?: number): number;
-/** Parameters for row count calculation */
-type RowCountParams = {
-    /** Available height for the container */
-    height?: number;
-    /** Top padding/offset value */
-    top: number;
-    /** Bottom padding/offset value */
-    bottom: number;
-    /** Base unit for calculations */
-    base: number;
-};
-/**
- * Calculates the number of rows that fit in the available space.
- * Ensures at least one row is always returned.
- *
- * @param params - Parameters for calculation
- * @returns Number of rows that fit in the space
- */
-export declare function calculateRowCount(params: RowCountParams): number;
-export {};

package/dist/utils/merge.d.ts

@@ -1,117 +0,0 @@
-import * as React from 'react';
-/**
- * Combines class names, filtering out falsy values.
- *
- * @remarks
- * - Filters out false, null, undefined
- * - Trims whitespace
- * - Preserves order of classes
- *
- * @param classes - Array of potential class names
- * @returns Combined class string
- *
- * @example
- * ```ts
- * mergeClasses('btn', isActive && 'active', undefined)
- * // => "btn active"
- * ```
- */
-export declare const mergeClasses: (...classes: Array<string | boolean | undefined | null>) => string;
-/**
- * Combines multiple style objects with type safety.
- *
- * @remarks
- * - Preserves type information
- * - Handles undefined values
- * - Merges deeply nested styles
- *
- * @param styles - Array of style objects
- * @returns Combined style object
- *
- * @example
- * ```ts
- * mergeStyles(
- *   { color: 'red' },
- *   isLarge && { fontSize: '2em' },
- *   customStyles
- * )
- * ```
- */
-export declare const mergeStyles: <T extends React.CSSProperties>(...styles: Array<T | undefined>) => T;
-/**
- * Merges multiple React refs into a single callback ref.
- *
- * @remarks
- * Handles:
- * - Function refs
- * - Object refs
- * - Undefined/null refs
- *
- * @param refs - Array of refs to merge
- * @returns Combined ref callback
- *
- * @example
- * ```tsx
- * const Component = React.forwardRef((props, ref) => {
- *   const localRef = useRef(null);
- *   const combinedRef = mergeRefs(ref, localRef);
- *
- *   return <div ref={combinedRef} />;
- * });
- * ```
- */
-export declare function mergeRefs<T>(...refs: Array<React.Ref<T> | null | undefined>): React.RefCallback<T>;
-/**
- * Parameters for creating a style override
- */
-export type StyleOverrideParams = {
-    /** CSS variable key to potentially override */
-    key: string;
-    /** Value to use if override is needed */
-    value: string;
-    /** Default styles to compare against */
-    defaultStyles: Record<string, string>;
-    /** Special case dimensions that should be skipped for specific values */
-    skipDimensions?: {
-        /** Dimensions that should be skipped when they're set to "fit-content" */
-        fitContent?: string[];
-        /** Dimensions that should be skipped when they're set to "auto" */
-        auto?: string[];
-        /** Dimensions that should be skipped when they're set to % values (like "100%") */
-        fullSize?: string[];
-    };
-};
-/**
- * Creates style overrides for CSS variables, conditionally based on comparison to defaults.
- * Only applies overrides when the value differs from the default, optimizing style objects.
- *
- * @param params - Style override parameters or individual arguments
- * @param value
- * @param defaultStyles
- * @returns Style object with override (if needed)
- *
- * @example
- * ```ts
- * // Object parameter style:
- * createStyleOverride({
- *   key: '--color',
- *   value: 'red',
- *   defaultStyles: { '--color': 'blue' }
- * })
- * // => { '--color': 'red' }
- *
- * // With dimension skipping:
- * createStyleOverride({
- *   key: '--width',
- *   value: 'fit-content',
- *   defaultStyles: { '--width': 'auto' },
- *   skipDimensions: { fitContent: ['--width', '--height'] }
- * })
- * // => {}
- *
- * // Legacy style with separate arguments:
- * createStyleOverride('--color', 'red', { '--color': 'blue' })
- * // => { '--color': 'red' }
- * ```
- */
-export declare function createStyleOverride(params: StyleOverrideParams | string, value?: string, defaultStyles?: Record<string, string>): Record<string, string | number>;

package/dist/utils/normalize.d.ts

@@ -1,30 +0,0 @@
-export interface NormalizationOptions {
-    /** Base unit for normalization */
-    base?: number;
-    /** Whether to round to nearest base multiple */
-    round?: boolean;
-    /** Optional value clamping */
-    clamp?: {
-        min?: number;
-        max?: number;
-    };
-    /** Suppress warning messages */
-    suppressWarnings?: boolean;
-}
-/**
- * Normalizes CSS values to a consistent format based on base unit.
- *
- * @param value - Value to normalize
- * @param options - Normalization configuration
- * @returns Normalized numeric value
- */
-export declare function normalizeValue(value: string | number | undefined, options?: NormalizationOptions): number;
-/**
- * Normalizes a pair of CSS values.
- *
- * @param values - Tuple of values to normalize
- * @param defaults - Default values if input is undefined
- * @param options - Normalization options
- * @returns Tuple of normalized values
- */
-export declare function normalizeValuePair(values: [string | number | undefined, string | number | undefined] | undefined, defaults: [number, number], options?: NormalizationOptions): [number, number];

package/dist/utils/padding.d.ts

@@ -1,11 +0,0 @@
-import { Padding, SpacingProps } from '@components';
-/**
- * Extract numeric top, right, bottom, left (in px) from `padding` or `block/inline`.
- * @param spacing - The props which may include padding, block, inline
- * @returns { top, right, bottom, left } with 0 defaults
- *
- * Priority (if padding is defined, it overrides block/inline):
- * - If `padding` is present, parse it fully (4 edges).
- * - Otherwise, parse `block` for top/bottom and `inline` for left/right.
- */
-export declare function parsePadding(spacing: SpacingProps): Padding;

package/dist/utils/parse.d.ts

@@ -1,18 +0,0 @@
-/**
- * Parses a CSS unit string into its numeric value and unit.
- *
- * @param value - CSS value string to parse
- * @returns Object with value and unit, or null if parsing fails
- */
-export declare function parseUnit(value: string): {
-    value: number;
-    unit: string;
-} | null;
-/**
- * Formats a value as a valid CSS string.
- *
- * @param value - Value to format
- * @param defaultValue - Optional default if value is undefined
- * @returns Formatted CSS string
- */
-export declare function formatValue(value: string | number | undefined, defaultValue?: number): string;

package/dist/utils/snapping.d.ts

@@ -1,28 +0,0 @@
-import { SnappingMode, Padding, PaddingValue } from '@components';
-/**
- * Calculates spacing adjustments to maintain baseline grid alignment.
- *
- * @remarks
- * Provides different snapping behaviors:
- * - none: No adjustments
- * - height: Adjusts bottom padding only
- * - clamp: Adjusts both top and bottom padding
- *
- * @param height - Measured element height
- * @param base - Grid base unit
- * @param initial - Initial spacing values
- * @param snapping - Snapping mode to apply
- * @returns Adjusted spacing values
- *
- * @example
- * ```ts
- * // Height snapping mode
- * calculateSnappedSpacing(46, 8, { top: 10, bottom: 10 }, 'height')
- * // => { top: 10, right: 0, bottom: 12, left: 0 }
- *
- * // Clamp mode
- * calculateSnappedSpacing(45, 8, { top: 10, bottom: 6 }, 'clamp')
- * // => { top: 2, right: 0, bottom: 1, left: 0 }
- * ```
- */
-export declare function calculateSnappedSpacing(height: number, base: number, initial: PaddingValue, snapping: SnappingMode): Padding;

package/dist/utils/ssr.d.ts

@@ -1,26 +0,0 @@
-/**
- * Detects if code is running in a server-side environment
- */
-export declare const isSSR: boolean;
-/**
- * Default dimensions to use during server-side rendering
- */
-export declare const SSR_DIMENSIONS: {
-    width: number;
-    height: number;
-};
-/**
- * Safe window-using function that works in both server and client
- * @param clientFn Function that uses window/browser APIs
- * @param fallback Fallback value to use in SSR environment
- * @returns Result of clientFn in browser, fallback in SSR
- */
-export declare function safeClientValue<T>(clientFn: () => T, fallback: T): T;
-/**
- * Returns a stable value during SSR and initial render, then switches to
- * the dynamic value after hydration
- * @param isHydrated Boolean indicating if component is hydrated
- * @param ssrValue Value to use during SSR/initial render
- * @param dynamicValue Value to use after hydration
- */
-export declare function hydratedValue<T>(isHydrated: boolean, ssrValue: T, dynamicValue: T): T;

package/dist/utils/timing.d.ts

@@ -1,45 +0,0 @@
-/**
- * Creates a debounced version of a function.
- *
- * @remarks
- * Useful for:
- * - Handling rapid event sequences
- * - Limiting API calls
- * - Performance optimization
- *
- * @param fn - Function to debounce
- * @param delay - Delay in milliseconds
- * @returns Debounced function
- *
- * @example
- * ```ts
- * const handleResize = debounce(() => {
- *   // Expensive calculation
- * }, 100);
- *
- * window.addEventListener('resize', handleResize);
- * ```
- */
-export declare const debounce: <T extends (...args: unknown[]) => void>(fn: T, delay: number) => [T, () => void];
-/**
- * Creates a requestAnimationFrame-based throttled function.
- *
- * @remarks
- * Optimizes performance by:
- * - Limiting execution to animation frames
- * - Preventing rapid-fire calls
- * - Maintaining visual smoothness
- *
- * @param fn - Function to throttle
- * @returns RAF-throttled function
- *
- * @example
- * ```ts
- * const updateScroll = rafThrottle(() => {
- *   // Update scroll position
- * });
- *
- * document.addEventListener('scroll', updateScroll);
- * ```
- */
-export declare const rafThrottle: <T extends (...args: never[]) => void>(fn: T) => T;