baseline-kit 2.0.0 → 2.1.0

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

@@ -1,10 +1,24 @@
-/**
- * @file Padder Component
- * @description Low-level padding management with visual debugging
- * @module components
- */
 import * as React from 'react';
+import { Variant } from '../types';
 import { IndicatorNode } from '../Spacer';
+import { DebuggingMode } from '@/components';
+type RenderSpacerFn = (width: React.CSSProperties['width'], height: React.CSSProperties['height']) => React.ReactNode;
+type PaddingStyles = {
+    paddingBlock?: string;
+    paddingInline?: string;
+    [key: string]: string | undefined;
+};
+/** Creates default container styles for Padder */
+export declare const createPadderContainerStyles: (width: React.CSSProperties["width"], height: React.CSSProperties["height"], base: number, color: string) => Record<string, string>;
+/** Creates padding styles when spacers are disabled */
+export declare const createDirectPaddingStyles: (enableSpacers: boolean, padding: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}) => PaddingStyles;
+/** Creates a render function for spacers */
+export declare const createRenderSpacerFn: (variant: Variant | undefined, debugging: DebuggingMode | undefined, indicatorNode?: IndicatorNode) => RenderSpacerFn;
 /**
  * A foundational component that manages consistent padding with visual debugging.
  *
@@ -51,11 +65,14 @@ import { IndicatorNode } from '../Spacer';
 export declare const Padder: React.NamedExoticComponent<{
     /** Render function for custom measurement indicators */
     indicatorNode?: IndicatorNode;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
     children?: React.ReactNode;
 } & {
-    debugging?: import("..").DebuggingMode;
+    debugging?: DebuggingMode;
     className?: string;
     style?: React.CSSProperties;
     height?: React.CSSProperties["height"];
     width?: React.CSSProperties["width"];
-} & import("..").SpacingProps & React.RefAttributes<HTMLDivElement>>;
+} & import("@/components").SpacingProps & React.RefAttributes<HTMLDivElement>>;
+export {};

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

@@ -1,55 +1,52 @@
-/**
- * @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 IndicatorNode = (value: number, type: 'width' | 'height') => React.ReactNode;
 export type SpacerProps = {
-    /** Render function for custom measurement display */
-    indicatorNode?: IndicatorNode;
-    /** Visual style when debugging is enabled */
+    /** 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;
-    /** Color override for visual indicators */
-    color?: string;
+    /** 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 default spacer styles */
+export declare const createDefaultSpacerStyles: (base: number, textColor: string, flatColor: string, lineColor: string) => Record<string, string>;
+/** Generates measurement indicators for debugging */
+export declare const generateMeasurements: (isShown: boolean, indicatorNode: SpacerProps["indicatorNode"], normWidth: number | string, normHeight: number | string) => React.ReactNode | null;
 /**
- * A flexible layout element that adds precise vertical or horizontal spacing.
+ * Creates empty space for implementing margins, gaps, and spacing.
  *
  * @remarks
- * Spacer provides:
- * - Consistent spacing in layouts
- * - Optional measurement indicators for debugging
- * - Multiple visual styles for different debugging needs
- * - Automatic dimension normalization
+ * - 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
- * // Basic vertical spacing
- * <Spacer
- *   height="24px"
- *   base={8}
- * />
+ * // Fixed size spacer
+ * <Spacer width={32} height={16} />
  *
- * // Custom style with indicators
+ * // Percentage-based spacer with debug hints
  * <Spacer
- *   width="32px"
- *   height="100%"
- *   base={4}
- *   color="#ff0000"
+ *   width="50%"
+ *   height={32}
  *   debugging="visible"
- *   indicatorNode={(value, dim) => `${dim}: ${value}px`}
+ *   variant="line"
  * />
+ *
+ * // Full-width spacer
+ * <Spacer height={64} />
  * ```
  */
 export declare const Spacer: React.NamedExoticComponent<SpacerProps>;

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

@@ -1,28 +1,44 @@
-/**
- * @file Stack Component
- * @description Flex container with baseline grid alignment
- * @module components
- */
 import * as React from 'react';
-import type { Gaps, IndicatorNode } from '@components';
+import type { Gaps } from '@components';
+import { IndicatorNode } from '../Spacer';
 import { ComponentsProps, Variant } from '../types';
+export declare const DIRECTION_AXIS: Record<string, React.CSSProperties['flexDirection']>;
+export type CSSPropertiesDirectionalAxis = keyof typeof DIRECTION_AXIS;
 export type StackProps = {
     /** Main axis orientation */
-    direction?: 'row' | 'column';
+    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 "fit-content") */
+    /** Container width (defaults to "auto") */
     width?: React.CSSProperties['width'];
-    /** Container height (defaults to "fit-content") */
+    /** 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 & Gaps;
+} & ComponentsProps;
+/** Creates default stack styles with theme colors */
+export declare const createDefaultStackStyles: (colors: Record<string, string>) => {
+    '--bkkw': string;
+    '--bkkh': string;
+    '--bkkcl': string;
+    '--bkkcf': string;
+    '--bkkci': string;
+};
+/** Creates gap styles for the stack */
+export declare const createStackGapStyles: (rowGap?: number, columnGap?: number, gap?: number) => Record<string, number | undefined>;
 /**
  * A flexible container component aligning children to the baseline grid.
  *
@@ -34,7 +50,7 @@ export type StackProps = {
  * - Includes visual debug overlays
  *
  * Key features:
- * - Automatic dimension management (defaults to fit-content)
+ * - Automatic dimension management (defaults to auto)
  * - Direct padding application in non-debug mode
  * - Comprehensive alignment controls
  * - Theme-aware debug visuals

package/dist/components/types.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { DebuggingMode } from '@components';
+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.

package/dist/hooks/useBaseline.d.ts

@@ -1,72 +1,55 @@
-/**
- * @file useBaseline Hook
- * @description Manages baseline grid alignment calculations
- * @module hooks
- */
-import { RefObject } from 'react';
-import { SnappingMode, Padding } from '@components';
+import * as React from 'react';
+import type { SnappingMode, Padding } from '@components';
 export interface BaselineOptions {
-    /** Base unit for alignment calculations (default: 8) */
     base?: number;
-    /** Alignment strategy to apply (default: 'none') */
+    /** Snapping strategy: 'none' | 'height' | 'clamp'. */
     snapping?: SnappingMode;
-    /** Initial spacing configuration */
+    /** Initial padding config.  e.g. { top: 10, bottom: 20 } or just 8, etc. */
     spacing?: Partial<Padding> | number;
-    /** Enable console warnings for misalignments */
+    /** Whether to warn in the console if the measured height is not a multiple of base. */
     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.
+ *  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
+ *  @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 height to align
- * - 'clamp': Adjusts both height and spacing values
+ *  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 to measure
- * @param options - Configuration options for alignment behavior
- * @returns Object containing adjusted padding, alignment status, and height
+ *  @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
- * function MyComponent() {
- *   const ref = useRef<HTMLDivElement>(null);
- *   const { padding, isAligned } = useBaseline(ref, {
+ * export function MyComponent() {
+ *   const ref = useRef<HTMLDivElement>(null)
+ *   const { padding } = 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
+ *     spacing: {
+ *       top: 16,
+ *       bottom: 16
+ *     }
+ *    }}
+ *  >
+ *    Content
+ *  </div>
+ *  )
+ *  }
  */
-export declare function useBaseline(ref: RefObject<HTMLElement | null>, { base, snapping, spacing, warnOnMisalignment, }?: BaselineOptions): BaselineResult;
+export declare function useBaseline(ref: React.RefObject<HTMLElement | null>, { base, snapping, spacing, warnOnMisalignment, }?: BaselineOptions): BaselineResult;

package/dist/hooks/useConfig.d.ts

@@ -1,8 +1,3 @@
-/**
- * @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] & {

package/dist/hooks/useDebug.d.ts

@@ -1,9 +1,4 @@
-/**
- * @file useDebug Hook
- * @description Manages component debugging state
- * @module hooks
- */
-import { DebuggingMode } from '@components';
+import { DebuggingMode } from '../components/Config/Config';
 interface DebugResult {
     /** Whether debug visuals should be shown */
     isShown: boolean;

package/dist/hooks/useGuide.d.ts

@@ -1,9 +1,4 @@
-/**
- * @file useGuide Hook
- * @description Manages grid layout calculations for guide overlays
- * @module hooks
- */
-import { RefObject } from 'react';
+import * as React from 'react';
 import { GuideConfig } from '@components';
 export interface GuideResult {
     /** CSS grid template string */
@@ -63,4 +58,4 @@ export interface GuideResult {
  * }
  * ```
  */
-export declare function useGuide(ref: RefObject<HTMLElement | null>, config: GuideConfig): GuideResult;
+export declare function useGuide(ref: React.RefObject<HTMLElement | null>, config: GuideConfig): GuideResult;

package/dist/hooks/useMeasure.d.ts

@@ -1,9 +1,4 @@
-/**
- * @file useMeasure Hook
- * @description Tracks element dimensions using ResizeObserver
- * @module hooks
- */
-import { RefObject } from 'react';
+import * as React from 'react';
 export interface MeasureResult {
     /** Measured width in pixels */
     width: number;
@@ -15,18 +10,9 @@ export interface MeasureResult {
 /**
  * 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
+ * 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
@@ -34,7 +20,7 @@ export interface MeasureResult {
  * @example
  * ```tsx
  * function ResponsiveBox() {
- *   const ref = useRef<HTMLDivElement>(null);
+ *   const ref = React.useRef<HTMLDivElement>(null);
  *   const { width, height, refresh } = useMeasure(ref);
  *
  *   return (
@@ -46,4 +32,4 @@ export interface MeasureResult {
  * }
  * ```
  */
-export declare function useMeasure(ref: RefObject<HTMLElement | null>): MeasureResult;
+export declare function useMeasure(ref: React.RefObject<HTMLElement | null>): MeasureResult;

package/dist/hooks/useVirtual.d.ts

@@ -1,8 +1,3 @@
-/**
- * @file useVirtual Hook
- * @description Manages virtual scrolling calculations
- * @module hooks
- */
 import { RefObject } from 'react';
 type VirtualResult = {
     /** Total number of items/lines to virtualize */