baseline-kit 2.0.0

package/dist/components/Padder/Padder.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Padder Component
+ * @description Low-level padding management with visual debugging
+ * @module components
+ */
+import * as React from 'react';
+import { IndicatorNode } from '../Spacer';
+/**
+ * A foundational component that manages consistent padding with visual debugging.
+ *
+ * @remarks
+ * Padder is a low-level utility that:
+ * - Applies consistent padding around content
+ * - Supports visual debugging of spacing
+ * - Maintains baseline grid alignment
+ * - Uses Spacer components for visual padding representation
+ *
+ * When debugging is enabled (`"visible"` or `"hidden"`), padding is represented
+ * using Spacer components. When debugging is `"none"`, direct CSS padding is
+ * applied for better performance.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Padder block={16} inline={8}>
+ *   <div>Content with consistent padding</div>
+ * </Padder>
+ *
+ * // With debug visuals and custom indicators
+ * <Padder
+ *   block={[8, 16]}
+ *   inline={[16, 24]}
+ *   debugging="visible"
+ *   indicatorNode={(value, dim) => (
+ *     <span className="text-sm">{dim}: {value}px</span>
+ *   )}
+ * >
+ *   <div>Content with visible padding guides</div>
+ * </Padder>
+ *
+ * // Direct padding mode
+ * <Padder
+ *   block={16}
+ *   inline={24}
+ *   debugging="none"
+ * >
+ *   <div>Content with direct CSS padding</div>
+ * </Padder>
+ * ```
+ */
+export declare const Padder: React.NamedExoticComponent<{
+    /** Render function for custom measurement indicators */
+    indicatorNode?: IndicatorNode;
+    children?: React.ReactNode;
+} & {
+    debugging?: import("..").DebuggingMode;
+    className?: string;
+    style?: React.CSSProperties;
+    height?: React.CSSProperties["height"];
+    width?: React.CSSProperties["width"];
+} & import("..").SpacingProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,10 @@
+/**
+ * @file Padder Component Entry (components/Padder/index.ts)
+ * @description Low-level padding management with debugging support
+ * @module baseline-kit/components/Padder
+ *
+ * @remarks
+ * Core component for managing padding and spacing visualization
+ * in the baseline grid system.
+ */
+export * from './Padder';

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

@@ -0,0 +1,55 @@
+/**
+ * @file Spacer Component
+ * @description Flexible spacing element with measurement indicators
+ * @module components
+ */
+import * as React from 'react';
+import { ComponentsProps, Variant } from '../types';
+/**
+ * Function signature for custom measurement indicators.
+ *
+ * @param value - The measurement in pixels
+ * @param dimension - Which dimension is being measured ('width' | 'height')
+ * @returns React node to display as the indicator
+ */
+export type IndicatorNode = (value: number, dimension: 'width' | 'height') => React.ReactNode;
+export type SpacerProps = {
+    /** Render function for custom measurement display */
+    indicatorNode?: IndicatorNode;
+    /** Visual style when debugging is enabled */
+    variant?: Variant;
+    /** Base unit for measurements (defaults to theme value) */
+    base?: number;
+    /** Color override for visual indicators */
+    color?: string;
+} & ComponentsProps;
+/**
+ * A flexible layout element that adds precise vertical or horizontal spacing.
+ *
+ * @remarks
+ * Spacer provides:
+ * - Consistent spacing in layouts
+ * - Optional measurement indicators for debugging
+ * - Multiple visual styles for different debugging needs
+ * - Automatic dimension normalization
+ *
+ * @example
+ * ```tsx
+ * // Basic vertical spacing
+ * <Spacer
+ *   height="24px"
+ *   base={8}
+ * />
+ *
+ * // Custom style with indicators
+ * <Spacer
+ *   width="32px"
+ *   height="100%"
+ *   base={4}
+ *   color="#ff0000"
+ *   debugging="visible"
+ *   indicatorNode={(value, dim) => `${dim}: ${value}px`}
+ * />
+ * ```
+ */
+export declare const Spacer: React.NamedExoticComponent<SpacerProps>;

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

@@ -0,0 +1,10 @@
+/**
+ * @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

@@ -0,0 +1,77 @@
+/**
+ * @file Stack Component
+ * @description Flex container with baseline grid alignment
+ * @module components
+ */
+import * as React from 'react';
+import type { Gaps, IndicatorNode } from '@components';
+import { ComponentsProps, Variant } from '../types';
+export type StackProps = {
+    /** Main axis orientation */
+    direction?: 'row' | 'column';
+    /** Distribution of space on main axis */
+    justify?: React.CSSProperties['justifyContent'];
+    /** Alignment on cross axis */
+    align?: React.CSSProperties['alignItems'];
+    /** Container width (defaults to "fit-content") */
+    width?: React.CSSProperties['width'];
+    /** Container height (defaults to "fit-content") */
+    height?: React.CSSProperties['height'];
+    /** Custom measurement indicator renderer */
+    indicatorNode?: IndicatorNode;
+    /** Visual style in debug mode */
+    variant?: Variant;
+    children?: React.ReactNode;
+} & ComponentsProps & Gaps;
+/**
+ * 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 fit-content)
+ * - 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>;

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

@@ -0,0 +1,10 @@
+/**
+ * @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/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Component Exports (components/index.ts)
+ * @description Main entry point for baseline-kit components
+ * @module baseline-kit/components
+ */
+import './styles/index.css';
+export * from './Layout';
+export * from './Box';
+export * from './Stack';
+export * from './Guide';
+export * from './Baseline';
+export * from './Spacer';
+export * from './Padder';
+export * from './Config';
+export * from './types';

package/dist/components/types.d.ts

@@ -0,0 +1,102 @@
+import * as React from 'react';
+import { DebuggingMode } from '@components';
+/**
+ * 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/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file Hook Exports (hooks/index.ts)
+ * @description React hooks for baseline-kit functionality
+ * @module baseline-kit/hooks
+ */
+export * from './useMeasure';
+export * from './useVirtual';
+export * from './useBaseline';
+export * from './useGuide';
+export * from './useConfig';
+export * from './useDebug';

package/dist/hooks/useBaseline.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file useBaseline Hook
+ * @description Manages baseline grid alignment calculations
+ * @module hooks
+ */
+import { RefObject } from 'react';
+import { SnappingMode, Padding } from '@components';
+export interface BaselineOptions {
+    /** Base unit for alignment calculations (default: 8) */
+    base?: number;
+    /** Alignment strategy to apply (default: 'none') */
+    snapping?: SnappingMode;
+    /** Initial spacing configuration */
+    spacing?: Partial<Padding> | number;
+    /** Enable console warnings for misalignments */
+    warnOnMisalignment?: boolean;
+}
+export interface BaselineResult {
+    /** Final adjusted padding values */
+    padding: Padding;
+    /** Whether the measured height is a multiple of base */
+    isAligned: boolean;
+    /** Raw measured height in pixels */
+    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
+ * - Snapping values to the grid
+ * - Warning about misalignments
+ *
+ * Different snapping modes affect how spacing is adjusted:
+ * - 'none': Uses raw spacing values without adjustment
+ * - 'height': Adjusts only the final height to align
+ * - 'clamp': Adjusts both height and spacing values
+ *
+ * @param ref - Reference to the DOM element to measure
+ * @param options - Configuration options for alignment behavior
+ * @returns Object containing adjusted padding, alignment status, and height
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *   const { padding, isAligned } = useBaseline(ref, {
+ *     base: 8,
+ *     snapping: 'height',
+ *     spacing: { top: 10, bottom: 20 }
+ *   });
+ *
+ *   return (
+ *     <div
+ *       ref={ref}
+ *       style={{
+ *         paddingTop: padding.top,
+ *         paddingBottom: padding.bottom
+ *       }}
+ *     >
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @throws {Error} if base is less than 1
+ */
+export declare function useBaseline(ref: RefObject<HTMLElement | null>, { base, snapping, spacing, warnOnMisalignment, }?: BaselineOptions): BaselineResult;

package/dist/hooks/useConfig.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file useConfig Hook
+ * @description Manages component-specific theme configuration
+ * @module hooks
+ */
+import { Config } from '@components';
+/** Type helper that merges base configuration with component-specific settings. */
+export type ComponentConfig<K extends keyof Config> = Config[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 Config>(component: K): ComponentConfig<K>;

package/dist/hooks/useDebug.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file useDebug Hook
+ * @description Manages component debugging state
+ * @module hooks
+ */
+import { DebuggingMode } from '@components';
+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

@@ -0,0 +1,66 @@
+/**
+ * @file useGuide Hook
+ * @description Manages grid layout calculations for guide overlays
+ * @module hooks
+ */
+import { RefObject } 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: RefObject<HTMLElement | null>, config: GuideConfig): GuideResult;

package/dist/hooks/useMeasure.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file useMeasure Hook
+ * @description Tracks element dimensions using ResizeObserver
+ * @module hooks
+ */
+import { RefObject } 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.
+ *
+ * @remarks
+ * Provides responsive element measurements using ResizeObserver, with:
+ * - Performance optimization via RAF throttling
+ * - Cache to prevent unnecessary updates
+ * - Error handling and recovery
+ * - Manual refresh capability
+ *
+ * The hook automatically:
+ * - Initializes with 0x0 dimensions
+ * - Updates on element resize
+ * - Cleans up observers on unmount
+ * - Rounds dimensions to whole pixels
+ *
+ * @param ref - Reference to the DOM element to measure
+ * @returns Current dimensions and refresh function
+ *
+ * @example
+ * ```tsx
+ * function ResponsiveBox() {
+ *   const ref = 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: RefObject<HTMLElement | null>): MeasureResult;