baseline-kit 2.0.1 → 3.0.0

package/dist/components/Box/Box.d.ts

@@ -1,9 +1,5 @@
-/**
- * @file Box Component
- * @description A fundamental layout container with baseline grid alignment
- * @module components
- */
 import * as React from 'react';
+import { ComponentsProps } from '../types';
 /**
  * Determines how the Box component aligns to the baseline grid.
  *
@@ -13,6 +9,19 @@ import * as React from 'react';
  * - `clamp`: Both height and spacing values snap to base unit multiples
  */
 export type SnappingMode = 'none' | 'height' | 'clamp';
+export type BoxProps = {
+    /** Number of columns to span in a grid layout */
+    colSpan?: number;
+    /** Number of rows to span in a grid layout */
+    rowSpan?: number;
+    /** Shorthand for equal column and row span. Takes precedence over individual spans */
+    span?: number;
+    /** Controls baseline grid alignment behavior */
+    snapping?: SnappingMode;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
+    children?: React.ReactNode;
+} & ComponentsProps;
 /**
  * A foundational container component that ensures consistent spacing and baseline alignment.
  *
@@ -52,6 +61,8 @@ export declare const Box: React.NamedExoticComponent<{
     span?: number;
     /** Controls baseline grid alignment behavior */
     snapping?: SnappingMode;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
     children?: React.ReactNode;
 } & {
     debugging?: import("..").DebuggingMode;

package/dist/components/Config/Config.d.ts

@@ -1,10 +1,5 @@
-/**
- * @file Config Component
- * @description Theme and configuration provider for baseline-kit components
- * @module components
- */
 import * as React from 'react';
-import { BaselineVariant } from '@components';
+import { BaselineVariant } from '@/components';
 import type { GuideVariant, Variant } from '../types';
 /**
  * Controls component debugging visibility and behavior.
@@ -25,7 +20,7 @@ type Colors = {
     text: string;
 };
 /** Complete configuration schema for baseline-kit. */
-export type Config = {
+export type ConfigSchema = {
     /** Base unit for spacing calculations */
     base: number;
     /** Guide component configuration */
@@ -67,28 +62,76 @@ export type Config = {
         debugging: DebuggingMode;
     };
 };
-export declare const useDefaultConfig: () => Config;
+export declare const useDefaultConfig: () => ConfigSchema;
 type ConfigProps = {
     children: React.ReactNode;
     /** Base unit for spacing calculations */
     base?: number;
     /** Baseline component overrides */
-    baseline?: Partial<Config['baseline']>;
+    baseline?: Partial<ConfigSchema['baseline']>;
     /** Flex component overrides */
-    stack?: Partial<Config['stack']>;
+    stack?: Partial<ConfigSchema['stack']>;
     /** Layout component overrides */
-    layout?: Partial<Config['layout']>;
+    layout?: Partial<ConfigSchema['layout']>;
+    /** Guide component overrides */
+    guide?: Partial<ConfigSchema['guide']>;
+    /** Spacer component overrides */
+    spacer?: Partial<ConfigSchema['spacer']>;
+    /** Box component overrides */
+    box?: Partial<ConfigSchema['box']>;
+    /** Padder component overrides */
+    padder?: Partial<ConfigSchema['padder']>;
+};
+/** Parameters for creating CSS variables */
+type CSSVariablesParams = {
+    /** Base unit for spacing calculations */
+    base: number;
+    /** Baseline component configuration */
+    baseline: ConfigSchema['baseline'];
+    /** Guide component configuration */
+    guide: ConfigSchema['guide'];
+    /** Stack component configuration */
+    stack: ConfigSchema['stack'];
+    /** Spacer component configuration */
+    spacer: ConfigSchema['spacer'];
+    /** Layout component configuration */
+    layout: ConfigSchema['layout'];
+    /** Box component configuration */
+    box: ConfigSchema['box'];
+    /** Padder component configuration */
+    padder: ConfigSchema['padder'];
+};
+/**
+ * Creates CSS variables from the configuration object.
+ * These variables are used throughout the component library.
+ */
+export declare const createCSSVariables: (params: CSSVariablesParams) => Record<string, string>;
+/** Parameters for merging configuration */
+type MergeConfigParams = {
+    /** Parent configuration to extend */
+    parentConfig: ConfigSchema;
+    /** Base unit override */
+    base?: number;
+    /** Baseline component overrides */
+    baseline?: Partial<ConfigSchema['baseline']>;
     /** Guide component overrides */
-    guide?: Partial<Config['guide']>;
+    guide?: Partial<ConfigSchema['guide']>;
     /** Spacer component overrides */
-    spacer?: Partial<Config['spacer']>;
+    spacer?: Partial<ConfigSchema['spacer']>;
     /** Box component overrides */
-    box?: Partial<Config['box']>;
+    box?: Partial<ConfigSchema['box']>;
+    /** Stack component overrides */
+    stack?: Partial<ConfigSchema['stack']>;
+    /** Layout component overrides */
+    layout?: Partial<ConfigSchema['layout']>;
     /** Padder component overrides */
-    padder?: Partial<Config['padder']>;
+    padder?: Partial<ConfigSchema['padder']>;
 };
-/** Creates CSS variables from the configuration object. */
-export declare const createCSSVariables: ({ base, baseline, guide, stack, spacer, layout, box, padder, }: Config) => Record<string, string>;
+/**
+ * Merges parent config with overrides.
+ * Creates a new config object without mutating the parent.
+ */
+export declare const mergeConfig: (params: MergeConfigParams) => ConfigSchema;
 /**
  * Configuration provider for baseline-kit components.
  *

package/dist/components/Config/defaults.d.ts

@@ -3,7 +3,7 @@
  * @description Default theme and configuration values for baseline-kit
  * @module baseline-kit/components/Config
  */
-import type { Config } from './Config';
+import type { ConfigSchema } from './Config';
 /**
  * Default configuration for baseline-kit.
  *
@@ -22,4 +22,4 @@ import type { Config } from './Config';
  * The configuration is marked as const to ensure type safety
  * and prevent accidental modifications.
  */
-export declare const DEFAULT_CONFIG: Config;
+export declare const DEFAULT_CONFIG: ConfigSchema;

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

@@ -8,4 +8,4 @@
  * theme values and default settings.
  */
 export * from './Config';
-export * from './defaults';
+export { DEFAULT_CONFIG } from './defaults';

package/dist/components/Guide/Guide.d.ts

@@ -1,20 +1,29 @@
-/**
- * @file Guide Component
- * @description Visual grid overlay component for alignment and debugging
- * @module components
- */
 import * as React from 'react';
+import { ComponentsProps } from '@components';
 import { AutoConfig, FixedConfig, LineConfig, PatternConfig } from './types';
-import type { ComponentsProps } from '../types';
+import type { GuideVariant } from '../types';
 /** Merged configuration types that support various grid layout strategies */
 export type GuideConfig = PatternConfig | AutoConfig | FixedConfig | LineConfig;
 export type GuideProps = {
-    /**
-     * Controls horizontal alignment of columns within the container.
-     * @default "start"
-     */
-    align?: 'start' | 'center' | 'end';
-} & ComponentsProps & GuideConfig;
+    /** Controls horizontal alignment of columns within the container */
+    align?: React.CSSProperties['justifyContent'];
+    /** Visual style of the guide */
+    variant?: GuideVariant;
+    /** Number of columns (for fixed/auto variants) */
+    columns?: number | readonly (string | number | undefined | 'auto')[];
+    /** Column width (for fixed variant) */
+    columnWidth?: React.CSSProperties['width'];
+    /** Maximum width of the guide */
+    maxWidth?: React.CSSProperties['maxWidth'];
+    /** Color override for guide lines */
+    color?: React.CSSProperties['color'];
+    /** Content to render inside the guide */
+    children?: React.ReactNode;
+    /** Gap between columns */
+    gap?: number;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
+} & ComponentsProps & Omit<GuideConfig, 'columns' | 'columnWidth' | 'gap'>;
 /**
  * A developer tool component that provides visual grid overlays for alignment.
  *

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

@@ -2,11 +2,5 @@
  * @file Guide Component Entry (components/Guide/index.ts)
  * @description Visual grid overlay system for alignment
  * @module baseline-kit/components/Guide
- *
- * @remarks
- * Provides visual grid overlays for layout alignment with
- * multiple grid strategies and validation.
  */
 export * from './Guide';
-export * from './types';
-export * from './validation';

package/dist/components/Guide/types.d.ts

@@ -90,7 +90,7 @@ export type FixedConfig = BaseGuideConfig & {
  *
  * @example
  * ```ts
- * // Auto-fit columns of 200px
+ * // Auto-fill columns of 200px
  * const auto: AutoConfig = {
  *   variant: 'auto',
  *   columnWidth: '200px',

package/dist/components/Layout/Layout.d.ts

@@ -1,11 +1,8 @@
-/**
- * @file Layout Component
- * @description Grid-based layout component with baseline alignment
- * @module components
- */
 import * as React from 'react';
-import type { Gaps, IndicatorNode } from '@components';
+import type { Gaps } from '@components';
+import { Spacer } from '../Spacer';
 import { ComponentsProps, Variant } from '../types';
+type IndicatorNode = NonNullable<React.ComponentProps<typeof Spacer>['indicatorNode']>;
 export type LayoutProps = {
     /**
      * Grid column definition. Supports:
@@ -28,6 +25,12 @@ export type LayoutProps = {
     indicatorNode?: IndicatorNode;
     /** Visual style in debug mode */
     variant?: Variant;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
+    /** Container width (defaults to "auto") */
+    width?: React.CSSProperties['width'];
+    /** Container height (defaults to "auto") */
+    height?: React.CSSProperties['height'];
     children?: React.ReactNode;
 } & ComponentsProps & Gaps;
 /**
@@ -67,3 +70,4 @@ export type LayoutProps = {
  * ```
  */
 export declare const Layout: React.NamedExoticComponent<LayoutProps>;
+export {};

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

@@ -1,10 +1,14 @@
-/**
- * @file Padder Component
- * @description Low-level padding management with visual debugging
- * @module components
- */
 import * as React from 'react';
+import { ComponentsProps } from '../types';
 import { IndicatorNode } from '../Spacer';
+import { DebuggingMode } from '@/components';
+export type PadderProps = {
+    /** Render function for custom measurement indicators */
+    indicatorNode?: IndicatorNode;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
+    children?: React.ReactNode;
+} & ComponentsProps;
 /**
  * A foundational component that manages consistent padding with visual debugging.
  *
@@ -51,11 +55,13 @@ 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>>;

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

@@ -1,19 +1,48 @@
-/**
- * @file Spacer Component
- * @description Flexible spacing element with measurement indicators
- * @module components
- */
 import * as React from 'react';
 import { ComponentsProps, Variant } from '../types';
-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 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/Stack/Stack.d.ts

@@ -1,14 +1,12 @@
-/**
- * @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';
+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 */
@@ -21,8 +19,16 @@ export type StackProps = {
     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;
 /**
  * A flexible container component aligning children to the baseline grid.
  *
@@ -75,3 +81,4 @@ export type StackProps = {
  * ```
  */
 export declare const Stack: React.NamedExoticComponent<StackProps>;
+export {};

package/dist/components/index.d.ts

@@ -3,13 +3,14 @@
  * @description Main entry point for baseline-kit components
  * @module baseline-kit/components
  */
-import './styles/index.css';
+import './styles/core.css';
+import './styles/theme.css';
 export * from './Layout';
 export * from './Box';
 export * from './Stack';
-export * from './Guide';
-export * from './Baseline';
 export * from './Spacer';
 export * from './Padder';
+export * from './Guide';
+export * from './Baseline';
 export * from './Config';
 export * from './types';

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

@@ -0,0 +1,11 @@
+/**
+ * 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,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.
@@ -68,10 +68,10 @@ export type GuideColumnValue = string | number | undefined | 'auto';
 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];
+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];
+export type PaddedVariant = (typeof PADD_VARIANTS)[number];
 /**
  * Common props shared across library components.
  * Provides consistent sizing, spacing, styling, and debugging options.

package/dist/hooks/useBaseline.d.ts

@@ -1,4 +1,4 @@
-import { RefObject } from 'react';
+import * as React from 'react';
 import type { SnappingMode, Padding } from '@components';
 export interface BaselineOptions {
     base?: number;
@@ -34,22 +34,17 @@ export interface BaselineResult {
  *  @param options Configuration options for alignment behavior
  *  @returns Object with adjusted padding, alignment status, and height
  *
- *  @example
- *  function MyComponent() {
- *  const ref = useRef<HTMLDivElement>(null)
- *  const { padding, isAligned } = useBaseline(ref, {
- *  base: 8,
- *  snapping: 'height',
- *  spacing: { top: 10, bottom: 20 },
- *  warnOnMisalignment: true,
- *  })
- *
- *  return (
- *  <div
- *    ref={ref}
- *    style={{
- *      paddingTop: padding.top,
- *      paddingBottom: padding.bottom,
+ * @example
+ * ```tsx
+ * export function MyComponent() {
+ *   const ref = useRef<HTMLDivElement>(null)
+ *   const { padding } = useBaseline(ref, {
+ *     base: 8,
+ *     snapping: 'height',
+ *     spacing: {
+ *       top: 16,
+ *       bottom: 16
+ *     }
  *    }}
  *  >
  *    Content
@@ -57,4 +52,4 @@ export interface BaselineResult {
  *  )
  *  }
  */
-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,11 +1,6 @@
-/**
- * @file useConfig Hook
- * @description Manages component-specific theme configuration
- * @module hooks
- */
-import { Config } from '@components';
+import { ConfigSchema } from '@components';
 /** Type helper that merges base configuration with component-specific settings. */
-export type ComponentConfig<K extends keyof Config> = Config[K] & {
+export type ComponentConfig<K extends keyof ConfigSchema> = ConfigSchema[K] & {
     /** Base unit for spacing calculations */
     base: number;
 };
@@ -43,4 +38,4 @@ export type ComponentConfig<K extends keyof Config> = Config[K] & {
  * }
  * ```
  */
-export declare function useConfig<K extends keyof Config>(component: K): ComponentConfig<K>;
+export declare function useConfig<K extends keyof ConfigSchema>(component: K): ComponentConfig<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/useIsClient.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hook to determine if the code is running on the client side.
+ *
+ * @returns Boolean indicating if the code is running in a browser environment
+ */
+export declare function useIsClient(): boolean;

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 */