baseline-kit 3.0.2 → 5.0.0

package/dist/components/Spacer/Spacer.d.ts

@@ -1,48 +0,0 @@
-import * as React from 'react';
-import { ComponentsProps, Variant } from '../types';
-export type IndicatorNode = (value: number, type: 'width' | 'height') => React.ReactNode;
-export type SpacerProps = {
-    /** Explicit width (takes precedence over block) */
-    width?: React.CSSProperties['width'];
-    /** Explicit height (takes precedence over block) */
-    height?: React.CSSProperties['height'];
-    /** Visual style in debug mode */
-    variant?: Variant;
-    /** Color to use for debug visuals (overrides theme) */
-    color?: string;
-    /** Base unit for measurements (defaults to theme value) */
-    base?: number;
-    /** Custom content to render (for debugging info) */
-    children?: React.ReactNode;
-    /** Custom indicator node rendering function */
-    indicatorNode?: IndicatorNode;
-    /** Flag to enable SSR-compatible mode (simplified initial render) */
-    ssrMode?: boolean;
-} & ComponentsProps;
-/**
- * Creates empty space for implementing margins, gaps, and spacing.
- *
- * @remarks
- * - Flexible sizing: Set width and height directly
- * - Normalized values: All inputs convert to base unit multiples
- * - Debug visuals: Shows spacing measurements with theming
- * - Automatic: Empty in production, visible in debug mode
- *
- * @example
- * ```tsx
- * // Fixed size spacer
- * <Spacer width={32} height={16} />
- *
- * // Percentage-based spacer with debug hints
- * <Spacer
- *   width="50%"
- *   height={32}
- *   debugging="visible"
- *   variant="line"
- * />
- *
- * // Full-width spacer
- * <Spacer height={64} />
- * ```
- */
-export declare const Spacer: React.NamedExoticComponent<SpacerProps>;

package/dist/components/Spacer/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * @file Spacer Component Entry (components/Spacer/index.ts)
- * @description Spacing management component with measurement indicators
- * @module baseline-kit/components/Spacer
- *
- * @remarks
- * Provides both horizontal and vertical spacing with optional
- * visual debugging features.
- */
-export * from './Spacer';

package/dist/components/Stack/Stack.d.ts

@@ -1,84 +0,0 @@
-import * as React from 'react';
-import type { Gaps } from '@components';
-import { IndicatorNode } from '../Spacer';
-import { ComponentsProps, Variant } from '../types';
-declare const DIRECTION_AXIS: Record<string, React.CSSProperties['flexDirection']>;
-export type CSSPropertiesDirectionalAxis = keyof typeof DIRECTION_AXIS;
-export type StackProps = {
-    /** Main axis orientation */
-    direction?: React.CSSProperties['flexDirection'] & CSSPropertiesDirectionalAxis;
-    /** Distribution of space on main axis */
-    justify?: React.CSSProperties['justifyContent'];
-    /** Alignment on cross axis */
-    align?: React.CSSProperties['alignItems'];
-    /** Container width (defaults to "auto") */
-    width?: React.CSSProperties['width'];
-    /** Container height (defaults to "auto") */
-    height?: React.CSSProperties['height'];
-    /** Custom measurement indicator renderer */
-    indicatorNode?: IndicatorNode;
-    /** Visual style in debug mode */
-    variant?: Variant;
-    /** Gap between items in base units */
-    gap?: Gaps;
-    /** Row gap when using different values for rows and columns */
-    rowGap?: Gaps;
-    /** Column gap when using different values for rows and columns */
-    columnGap?: Gaps;
-    /** Flag to enable SSR-compatible mode (simplified initial render) */
-    ssrMode?: boolean;
-    children?: React.ReactNode;
-} & ComponentsProps;
-/**
- * A flexible container component aligning children to the baseline grid.
- *
- * @remarks
- * Stack provides a flex container that:
- * - Maintains baseline grid alignment
- * - Supports both row and column layouts
- * - Handles consistent spacing between items
- * - Includes visual debug overlays
- *
- * Key features:
- * - Automatic dimension management (defaults to auto)
- * - Direct padding application in non-debug mode
- * - Comprehensive alignment controls
- * - Theme-aware debug visuals
- *
- * @example
- * ```tsx
- * // Basic horizontal stack
- * <Stack gap={16}>
- *   <div>Item 1</div>
- *   <div>Item 2</div>
- * </Stack>
- *
- * // Vertical stack with alignment
- * <Stack
- *   direction="column"
- *   gap={24}
- *   align="center"
- *   justify="space-between"
- *   debugging="visible"
- * >
- *   <div>Top</div>
- *   <div>Middle</div>
- *   <div>Bottom</div>
- * </Stack>
- *
- * // Complex layout with padding
- * <Stack
- *   direction="row"
- *   gap={32}
- *   align="stretch"
- *   block={[16, 24]}
- *   inline={16}
- *   debugging="visible"
- * >
- *   <div>Panel 1</div>
- *   <div>Panel 2</div>
- * </Stack>
- * ```
- */
-export declare const Stack: React.NamedExoticComponent<StackProps>;
-export {};

package/dist/components/Stack/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * @file Stack/Flex Component Entry (components/Stack/index.ts)
- * @description Flexible container with baseline grid alignment
- * @module baseline-kit/components/Stack
- *
- * @remarks
- * While the component is called Stack internally, it's exported as Flex
- * for API consistency.
- */
-export * from './Stack';

package/dist/components/styles/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Baseline Kit Styles System
- *
- * This file exports all core styles needed for the component library.
- * The import order is important:
- * 1. core.css - Contains reset.css, base.css, and component styles
- * 2. theme.css - Contains color variables and theming
- */
-import './core.css';
-import './theme.css';
-export {};

package/dist/components/types.d.ts

@@ -1,102 +0,0 @@
-import * as React from 'react';
-import { DebuggingMode } from './Config/Config';
-/**
- * Defines spacing as either a single value, start/end pair, or object with explicit edges.
- * Used for block and inline spacing across components.
- *
- * @example
- * ```tsx
- * // Single value
- * <Box block={8} />
- *
- * // Start/end pair
- * <Box block={[8, 16]} />
- *
- * // Object with explicit values
- * <Box block={{ start: 8, end: 16 }} />
- * ```
- */
-export type Spacing = number | [number, number] | {
-    start?: number;
-    end?: number;
-};
-/**
- * Flexible padding definition that supports multiple formats for setting padding on all sides.
- *
- * @example
- * ```tsx
- * // Single value for all sides
- * padding={8}
- *
- * // Block and inline pairs
- * padding={[8, 16]}
- *
- * // Explicit values for each side
- * padding={[8, 16, 8, 16]}
- *
- * // Object with named sides
- * padding={{ top: 8, right: 16, bottom: 8, left: 16 }}
- * ```
- */
-export type PaddingValue = number | [number, number] | [number, number, number, number] | {
-    top?: number;
-    bottom?: number;
-    left?: number;
-    right?: number;
-};
-/** Resolved padding values for all edges after normalization. */
-export type Padding = {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
-};
-/** Props interface for components that support spacing configuration. */
-export type SpacingProps = {
-    padding?: PaddingValue;
-    block?: Spacing;
-    inline?: Spacing;
-};
-/** Controls how columns are laid out in grid components. */
-export type GuideVariant = 'line' | 'pattern' | 'fixed' | 'auto';
-/**
- * Valid value types for grid columns. Can be a CSS length, fractional unit,
- * or 'auto' for automatic sizing.
- */
-export type GuideColumnValue = string | number | undefined | 'auto';
-/** Array of column definitions for pattern-based grid layouts. */
-export type GuideColumnsPattern = readonly GuideColumnValue[];
-/** Valid grid alignment values. */
-export declare const GRID_ALIGNMENTS: readonly ["start", "center", "end"];
-export type GridAlignment = (typeof GRID_ALIGNMENTS)[number];
-/** Valid component variants affecting visual style. */
-export declare const PADD_VARIANTS: readonly ["line", "flat"];
-export type PaddedVariant = (typeof PADD_VARIANTS)[number];
-/**
- * Common props shared across library components.
- * Provides consistent sizing, spacing, styling, and debugging options.
- */
-export type ComponentsProps = {
-    debugging?: DebuggingMode;
-    className?: string;
-    style?: React.CSSProperties;
-    height?: React.CSSProperties['height'];
-    width?: React.CSSProperties['width'];
-} & SpacingProps;
-/** Base configuration for components that support padding. */
-export type PaddedBaseConfig = {
-    base?: number;
-    color?: React.CSSProperties['color'] | React.CSSProperties['backgroundColor'];
-    zIndex?: React.CSSProperties['zIndex'];
-};
-export type Variant = 'line' | 'flat' | 'pattern';
-export type Gaps = {
-    gap?: React.CSSProperties['gap'];
-    rowGap?: never;
-    columnGap?: never;
-} | {
-    /** When using separate gaps, omit unified gap */
-    gap?: never;
-    rowGap?: React.CSSProperties['rowGap'];
-    columnGap?: React.CSSProperties['columnGap'];
-};

package/dist/hooks/useBaseline.d.ts

@@ -1,55 +0,0 @@
-import * as React from 'react';
-import type { SnappingMode, Padding } from '@components';
-export interface BaselineOptions {
-    base?: number;
-    /** Snapping strategy: 'none' | 'height' | 'clamp'. */
-    snapping?: SnappingMode;
-    /** Initial padding config.  e.g. { top: 10, bottom: 20 } or just 8, etc. */
-    spacing?: Partial<Padding> | number;
-    /** Whether to warn in the console if the measured height is not a multiple of base. */
-    warnOnMisalignment?: boolean;
-}
-export interface BaselineResult {
-    padding: Padding;
-    isAligned: boolean;
-    height: number;
-}
-/**
- *  Hook for managing baseline grid alignment in components.
- *
- *  @remarks
- *  This hook handles the complex calculations needed to maintain baseline grid
- *  alignment, including:
- *    ▪	Measuring element dimensions
- *    ▪	Calculating padding adjustments
- *    ▪	Potentially snapping values to ensure multiples of the base
- *    ▪	Warning about misalignments in development
- *
- *  Different snapping modes affect how spacing is adjusted:
- *    ▪	'none': Uses raw spacing values without adjustment
- *    ▪	'height': Adjusts only the final (bottom) padding to align
- *    ▪	'clamp': Adjusts top and bottom to align
- *
- *  @param ref Reference to the DOM element
- *  @param options Configuration options for alignment behavior
- *  @returns Object with adjusted padding, alignment status, and height
- *
- * @example
- * ```tsx
- * export function MyComponent() {
- *   const ref = useRef<HTMLDivElement>(null)
- *   const { padding } = useBaseline(ref, {
- *     base: 8,
- *     snapping: 'height',
- *     spacing: {
- *       top: 16,
- *       bottom: 16
- *     }
- *    }}
- *  >
- *    Content
- *  </div>
- *  )
- *  }
- */
-export declare function useBaseline(ref: React.RefObject<HTMLElement | null>, { base, snapping, spacing, warnOnMisalignment, }?: BaselineOptions): BaselineResult;

package/dist/hooks/useConfig.d.ts

@@ -1,41 +0,0 @@
-import { ConfigSchema } from '@components';
-/** Type helper that merges base configuration with component-specific settings. */
-export type ComponentConfig<K extends keyof ConfigSchema> = ConfigSchema[K] & {
-    /** Base unit for spacing calculations */
-    base: number;
-};
-/**
- * Hook for accessing component-specific theme configuration.
- *
- * @remarks
- * This hook provides:
- * - Access to component-specific theme settings
- * - Automatic base unit inheritance
- * - Memoized configuration to prevent unnecessary updates
- * - Type-safe configuration access
- *
- * It merges:
- * - Global base unit settings
- * - Component-specific configurations
- * - Theme-based color schemes
- *
- * @param component - Name of the component requesting configuration
- * @returns Merged configuration for the specific component
- *
- * @example
- * ```tsx
- * function Box() {
- *   const config = useConfig('box');
- *
- *   return (
- *     <div style={{
- *       '--box-base': `${config.base}px`,
- *       '--box-color': config.colors.line
- *     }}>
- *       {children}
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useConfig<K extends keyof ConfigSchema>(component: K): ComponentConfig<K>;

package/dist/hooks/useDebug.d.ts

@@ -1,49 +0,0 @@
-import { DebuggingMode } from '../components/Config/Config';
-interface DebugResult {
-    /** Whether debug visuals should be shown */
-    isShown: boolean;
-    /** Whether debug features exist but are hidden */
-    isHidden: boolean;
-    /** Whether debug features are disabled */
-    isNone: boolean;
-    /** Current debugging mode */
-    debugging: DebuggingMode | undefined;
-}
-/**
- * Hook for managing component debug state and visibility.
- *
- * @remarks
- * Determines the active debugging mode by:
- * - Using prop value if provided
- * - Falling back to config value if prop is undefined
- * - Computing visibility states based on active mode
- *
- * This hook helps components:
- * - Control debug visual rendering
- * - Manage debug feature states
- * - Handle prop/config inheritance
- *
- * @param debuggingProp - Optional debugging mode from props
- * @param debuggingConfig - Debugging mode from theme/config
- * @returns Debug state information
- *
- * @example
- * ```tsx
- * function DebugComponent({ debugging: debugProp }) {
- *   const { isShown, isHidden, isNone } = useDebug(
- *     debugProp,
- *     'hidden' // Default from config
- *   );
- *
- *   return (
- *     <div>
- *       {isShown && <DebugOverlay />}
- *       {!isNone && <DebugFeatures />}
- *       <Content />
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useDebug(debuggingProp?: DebuggingMode, debuggingConfig?: DebuggingMode): DebugResult;
-export {};

package/dist/hooks/useGuide.d.ts

@@ -1,61 +0,0 @@
-import * as React from 'react';
-import { GuideConfig } from '@components';
-export interface GuideResult {
-    /** CSS grid template string */
-    template: string;
-    /** Total number of columns */
-    columnsCount: number;
-    /** Final gap size in pixels */
-    calculatedGap: number;
-    /** Whether the configuration is valid */
-    isValid: boolean;
-}
-/**
- * Hook for calculating grid layout parameters based on container dimensions.
- *
- * @remarks
- * This hook handles complex grid calculations for different layout variants:
- * - 'line': Evenly spaced vertical lines
- * - 'pattern': Custom repeating column patterns
- * - 'fixed': Set number of columns with optional width
- * - 'auto': Dynamic columns based on available space
- *
- * Key features:
- * - Responsive grid calculations
- * - Pattern validation
- * - Gap management
- * - Error handling
- *
- * @param ref - Reference to container element
- * @param config - Grid configuration object
- * @returns Grid calculation results
- *
- * @example
- * ```tsx
- * function GridOverlay() {
- *   const ref = useRef<HTMLDivElement>(null);
- *   const { template, columnsCount } = useGuide(ref, {
- *     variant: 'fixed',
- *     columns: 12,
- *     gap: 16,
- *     base: 8
- *   });
- *
- *   return (
- *     <div
- *       ref={ref}
- *       style={{
- *         display: 'grid',
- *         gridTemplateColumns: template,
- *         gap: calculatedGap
- *       }}
- *     >
- *       {Array(columnsCount).fill(null).map((_, i) => (
- *         <div key={i} className="grid-line" />
- *       ))}
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useGuide(ref: React.RefObject<HTMLElement | null>, config: GuideConfig): GuideResult;

package/dist/hooks/useMeasure.d.ts

@@ -1,35 +0,0 @@
-import * as React from 'react';
-export interface MeasureResult {
-    /** Measured width in pixels */
-    width: number;
-    /** Measured height in pixels */
-    height: number;
-    /** Function to force a remeasurement */
-    refresh: () => void;
-}
-/**
- * Hook for measuring and tracking DOM element dimensions.
- *
- * Provides responsive element measurements using ResizeObserver,
- * with performance optimization (via RAF throttling), error handling,
- * and a manual refresh method.
- *
- * @param ref - Reference to the DOM element to measure
- * @returns Current dimensions and refresh function
- *
- * @example
- * ```tsx
- * function ResponsiveBox() {
- *   const ref = React.useRef<HTMLDivElement>(null);
- *   const { width, height, refresh } = useMeasure(ref);
- *
- *   return (
- *     <div ref={ref} className="responsive-box">
- *       Width: {width}px, Height: {height}px
- *       <button onClick={refresh}>Remeasure</button>
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useMeasure(ref: React.RefObject<HTMLElement | null>): MeasureResult;

package/dist/hooks/useVirtual.d.ts

@@ -1,60 +0,0 @@
-import { RefObject } from 'react';
-type VirtualResult = {
-    /** Total number of items/lines to virtualize */
-    totalLines: number;
-    /** Height of each item in pixels */
-    lineHeight: number;
-    /** Reference to the scrollable container */
-    containerRef: RefObject<HTMLDivElement | null>;
-    /** Additional items to render above/below viewport */
-    buffer?: number | string;
-};
-/**
- * Hook for optimizing large lists through virtual scrolling.
- *
- * @remarks
- * This hook helps manage virtual scrolling by:
- * - Calculating visible item ranges
- * - Handling scroll events efficiently
- * - Managing buffer zones for smooth scrolling
- * - Supporting dynamic container sizes
- *
- * Performance optimizations:
- * - RAF-based scroll handling
- * - Intersection Observer for visibility
- * - Buffer zones to prevent flicker
- * - Efficient range calculations
- *
- * @param options - Virtual scrolling configuration
- * @returns Object containing start and end indices of visible items
- *
- * @example
- * ```tsx
- * function VirtualList() {
- *   const containerRef = useRef<HTMLDivElement>(null);
- *   const { start, end } = useVirtual({
- *     totalLines: 1000,
- *     lineHeight: 30,
- *     containerRef,
- *     buffer: 5
- *   });
- *
- *   return (
- *     <div ref={containerRef} className="scroll-container">
- *       <div style={{ height: 1000 * 30 }}>
- *         {items.slice(start, end).map(item => (
- *           <div key={item.id} style={{ height: 30 }}>
- *             {item.content}
- *           </div>
- *         ))}
- *       </div>
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useVirtual({ totalLines, lineHeight, containerRef, buffer, }: VirtualResult): {
-    start: number;
-    end: number;
-};
-export {};

package/dist/styles.d.ts

@@ -1,6 +0,0 @@
-/**
- * @file Style Entry Point
- * @description Clean import path for core CSS styles
- * @module baseline-kit/styles
- */
-import './components/styles/core.css';

package/dist/theme.d.ts

@@ -1,6 +0,0 @@
-/**
- * @file Theme Entry Point
- * @description Clean import path for theme CSS styles
- * @module baseline-kit/theme
- */
-import './components/styles/theme.css';

package/dist/utils/convert.d.ts

@@ -1,24 +0,0 @@
-export interface ConversionContext {
-    /** Parent element dimension for relative units */
-    parentSize?: number;
-    /** Viewport width for vw units */
-    viewportWidth?: number;
-    /** Viewport height for vh units */
-    viewportHeight?: number;
-    /** Root font size for rem units */
-    rootFontSize?: number;
-    /** Parent font size for em units */
-    parentFontSize?: number;
-}
-/** Conversion factors for absolute units to pixels */
-export declare const ABSOLUTE_UNIT_CONVERSIONS: Record<string, number>;
-/** Supported relative CSS units */
-export declare const RELATIVE_UNITS: string[];
-/**
- * Converts CSS values to pixels.
- *
- * @param value - CSS value to convert
- * @param context - Optional context for relative unit conversion
- * @returns Value in pixels or null if conversion fails
- */
-export declare function convertValue(value: number | string | undefined, context?: ConversionContext): number | null;

package/dist/utils/grid.d.ts

@@ -1,22 +0,0 @@
-/**
- * @file grid.ts
- * @description Grid layout utilities
- * @module utils
- */
-import * as React from 'react';
-/**
- * Creates grid span styles based on span props.
- * Handles both combined span and individual col/row span values.
- *
- * @param span - Optional equal span for both rows and columns
- * @param colSpan - Optional column span value
- * @param rowSpan - Optional row span value
- * @returns CSS properties object with grid span values
- *
- * @example
- * ```ts
- * createGridSpanStyles(2) // => { gridColumn: "span 2", gridRow: "span 2" }
- * createGridSpanStyles(undefined, 3, 2) // => { gridColumn: "span 3", gridRow: "span 2" }
- * ```
- */
-export declare const createGridSpanStyles: (span?: number, colSpan?: number, rowSpan?: number) => React.CSSProperties;

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 {};