baseline-kit 2.0.0

package/dist/components/Baseline/Baseline.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file Baseline Component
+ * @description Horizontal grid overlay for baseline alignment
+ * @module components
+ */
+import { ComponentsProps } from '@components';
+import { Variant } from '../types';
+export type BaselineVariant = Exclude<Variant, 'pattern'>;
+export type BaselineProps = {
+    /** Visual style variant for the baseline guides */
+    variant?: BaselineVariant;
+    /** Explicit width for the overlay (e.g., "1200px" or 1200) */
+    width?: number | string;
+    /** Explicit height for the overlay (e.g., "100vh" or 800) */
+    height?: number | string;
+    /** Base unit for measurements (defaults to theme value) */
+    base?: number;
+} & ComponentsProps;
+/**
+ * Renders horizontal guidelines for maintaining vertical rhythm and baseline alignment.
+ *
+ * @remarks
+ * Baseline provides horizontal guides that:
+ * - Help maintain consistent vertical spacing
+ * - Support visual verification of baseline alignment
+ * - Optimize performance through virtual rendering
+ * - Adapt to container dimensions
+ *
+ * @example
+ * ```tsx
+ * // Basic baseline overlay
+ * <Baseline
+ *   height="100vh"
+ *   base={8}
+ *   debugging="visible"
+ * />
+ *
+ * // Custom variant with padding
+ * <Baseline
+ *   variant="flat"
+ *   height="100vh"
+ *   base={4}
+ *   block={[16, 0]}
+ *   debugging="visible"
+ * />
+ * ```
+ */
+export declare const Baseline: import("react").NamedExoticComponent<BaselineProps>;

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

@@ -0,0 +1,6 @@
+/**
+ * @file Baseline Component Exports (components/Baseline/index.ts)
+ * @description Baseline component entry point
+ * @module baseline-kit/components/Baseline
+ */
+export * from './Baseline';

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

@@ -0,0 +1,62 @@
+/**
+ * @file Box Component
+ * @description A fundamental layout container with baseline grid alignment
+ * @module components
+ */
+import * as React from 'react';
+/**
+ * Determines how the Box component aligns to the baseline grid.
+ *
+ * @remarks
+ * - `none`: No snapping; uses raw spacing values as provided
+ * - `height`: Only container height snaps to base unit multiples
+ * - `clamp`: Both height and spacing values snap to base unit multiples
+ */
+export type SnappingMode = 'none' | 'height' | 'clamp';
+/**
+ * A foundational container component that ensures consistent spacing and baseline alignment.
+ *
+ * @remarks
+ * Box provides a layout container that:
+ * - Ensures consistent spacing aligned to the baseline grid
+ * - Supports grid layout integration through span props
+ * - Offers configurable snapping modes for fine-grained alignment control
+ * - Includes debug overlays for visual alignment verification
+ *
+ * By default, Box uses "fit-content" for both width and height unless explicitly specified.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with spacing
+ * <Box block={16} inline={8}>
+ *   <p>Content aligned to baseline</p>
+ * </Box>
+ *
+ * // With grid spanning and custom snapping
+ * <Box
+ *   colSpan={2}
+ *   rowSpan={1}
+ *   snapping="height"
+ *   debugging="visible"
+ * >
+ *   <p>Grid-integrated content</p>
+ * </Box>
+ * ```
+ */
+export declare const Box: React.NamedExoticComponent<{
+    /** 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;
+    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/Box/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Box Component Exports (components/Box/index.ts)
+ * @description Box component entry point
+ * @module baseline-kit/components/Box
+ */
+export * from './Box';

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

@@ -0,0 +1,136 @@
+/**
+ * @file Config Component
+ * @description Theme and configuration provider for baseline-kit components
+ * @module components
+ */
+import * as React from 'react';
+import { BaselineVariant } from '@components';
+import type { GuideVariant, Variant } from '../types';
+/**
+ * Controls component debugging visibility and behavior.
+ *
+ * @remarks
+ * - `none`: Debug features are fully disabled
+ * - `hidden`: Debug elements exist in DOM but are not visible
+ * - `visible`: Debug elements are fully rendered and visible
+ */
+export type DebuggingMode = 'none' | 'hidden' | 'visible';
+/** Color configuration for component themes. */
+type Colors = {
+    /** Color for line-based visuals */
+    line: string;
+    /** Color for flat surface visuals */
+    flat: string;
+    /** Color for measurement indicators */
+    indice: string;
+};
+/** Complete configuration schema for baseline-kit. */
+export type Config = {
+    /** Base unit for spacing calculations */
+    base: number;
+    /** Guide component configuration */
+    guide: {
+        variant: GuideVariant;
+        debugging: DebuggingMode;
+        colors: Record<GuideVariant, string>;
+    };
+    /** Baseline component configuration */
+    baseline: {
+        variant: BaselineVariant;
+        debugging: DebuggingMode;
+        colors: Record<BaselineVariant, string>;
+    };
+    /** Stack component configuration */
+    stack: {
+        colors: Colors;
+        debugging: DebuggingMode;
+    };
+    /** Layout component configuration */
+    layout: {
+        colors: Colors;
+        debugging: DebuggingMode;
+    };
+    /** Spacer component configuration */
+    spacer: {
+        variant: Variant;
+        debugging: DebuggingMode;
+        colors: Colors;
+    };
+    /** Box component configuration */
+    box: {
+        colors: Colors;
+        debugging: DebuggingMode;
+    };
+    /** Padder component configuration */
+    padder: {
+        color: string;
+        debugging: DebuggingMode;
+    };
+};
+export declare const useDefaultConfig: () => Config;
+type ConfigProps = {
+    children: React.ReactNode;
+    /** Base unit for spacing calculations */
+    base?: number;
+    /** Baseline component overrides */
+    baseline?: Partial<Config['baseline']>;
+    /** Flex component overrides */
+    stack?: Partial<Config['stack']>;
+    /** Layout component overrides */
+    layout?: Partial<Config['layout']>;
+    /** Guide component overrides */
+    guide?: Partial<Config['guide']>;
+    /** Spacer component overrides */
+    spacer?: Partial<Config['spacer']>;
+    /** Box component overrides */
+    box?: Partial<Config['box']>;
+    /** Padder component overrides */
+    padder?: Partial<Config['padder']>;
+};
+/** Creates CSS variables from the configuration object. */
+export declare const createCSSVariables: ({ base, baseline, guide, stack, spacer, layout, box, padder, }: Config) => Record<string, string>;
+/**
+ * Configuration provider for baseline-kit components.
+ *
+ * @remarks
+ * Config provides theme and debugging settings to all nested components.
+ * It allows for:
+ * - Global base unit configuration
+ * - Component-specific color themes
+ * - Debug mode control
+ * - Visual style customization
+ *
+ * Configs can be nested to override settings for specific sections.
+ *
+ * @example
+ * ```tsx
+ * // Basic global configuration
+ * <Config base={8}>
+ *   <App />
+ * </Config>
+ *
+ * // Component-specific overrides
+ * <Config
+ *   base={8}
+ *   guide={{
+ *     debugging: "visible",
+ *     colors: {
+ *       line: "rgba(255,0,0,0.2)",
+ *       pattern: "rgba(0,0,255,0.2)"
+ *     }
+ *   }}
+ * >
+ *   <Layout>...</Layout>
+ * </Config>
+ *
+ * // Nested configurations
+ * <Config base={8}>
+ *   <div>Uses 8px base</div>
+ *   <Config base={4}>
+ *     <div>Uses 4px base</div>
+ *   </Config>
+ * </Config>
+ * ```
+ */
+export declare function Config({ children, base, stack, baseline, guide, layout, spacer, box, padder, }: ConfigProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * @file defaults.ts
+ * @description Default theme and configuration values for baseline-kit
+ * @module baseline-kit/components/Config
+ */
+import type { Config } from './Config';
+/**
+ * Default configuration for baseline-kit.
+ *
+ * @remarks
+ * Provides the base configuration for all components including:
+ * - Base unit for spacing calculations (8px default)
+ * - Default component variants
+ * - Initial debugging modes
+ * - Theme color assignments
+ *
+ * Each component section includes:
+ * - Visual variant selection (where applicable)
+ * - Debugging mode setting
+ * - Color theme assignments
+ *
+ * The configuration is marked as const to ensure type safety
+ * and prevent accidental modifications.
+ */
+export declare const DEFAULT_CONFIG: Config;

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

@@ -0,0 +1,11 @@
+/**
+ * @file Config Component Entry (components/Config/index.ts)
+ * @description Theme and configuration provider
+ * @module baseline-kit/components/Config
+ *
+ * @remarks
+ * Central configuration system for baseline-kit, managing
+ * theme values and default settings.
+ */
+export * from './Config';
+export * from './defaults';

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

@@ -0,0 +1,60 @@
+/**
+ * @file Guide Component
+ * @description Visual grid overlay component for alignment and debugging
+ * @module components
+ */
+import { AutoConfig, FixedConfig, LineConfig, PatternConfig } from './types';
+import type { ComponentsProps } 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;
+/**
+ * A developer tool component that provides visual grid overlays for alignment.
+ *
+ * @remarks
+ * Guide renders a configurable grid overlay that helps visualize:
+ * - Column layouts and spacing
+ * - Content alignment
+ * - Layout patterns
+ *
+ * The component supports multiple variants:
+ * - "line": Simple evenly-spaced vertical lines
+ * - "pattern": Custom repeating column width patterns
+ * - "fixed": Fixed number of equal or custom-width columns
+ * - "auto": Dynamically calculated columns based on container width
+ *
+ * @example
+ * ```tsx
+ * // Basic column guide
+ * <Guide
+ *   variant="line"
+ *   gap={8}
+ *   debugging="visible"
+ * />
+ *
+ * // Custom column pattern
+ * <Guide
+ *   variant="pattern"
+ *   columns={['100px', '1fr', '2fr']}
+ *   gap={16}
+ *   align="center"
+ *   debugging="visible"
+ * />
+ *
+ * // Fixed columns with custom width
+ * <Guide
+ *   variant="fixed"
+ *   columns={12}
+ *   columnWidth="60px"
+ *   gap={8}
+ *   debugging="visible"
+ * />
+ * ```
+ */
+export declare const Guide: import("react").NamedExoticComponent<GuideProps>;

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

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

@@ -0,0 +1,144 @@
+/**
+ * @file types.ts
+ * @description Type definitions for Guide component configurations
+ * @module baseline-kit/components/Guide/types
+ */
+import * as React from 'react';
+import { GuideColumnsPattern } from '../types';
+/**
+ * Base configuration shared by all guide variants.
+ *
+ * @example
+ * ```ts
+ * const baseConfig: BaseGuideConfig = {
+ *   gap: 2,     // 2px gap
+ *   base: 8     // 8px base unit
+ * }
+ * ```
+ */
+type BaseGuideConfig = {
+    /** Gap between columnms. */
+    gap?: React.CSSProperties['gap'];
+    /**
+     * Base unit in pixels for spacing calculations.
+     * Typically inherited from theme configuration.
+     */
+    base?: number;
+};
+/**
+ * Pattern-based grid configuration.
+ * Defines repeating column width patterns.
+ *
+ * @example
+ * ```ts
+ * // Three-column pattern: 100px | 200px | 100px
+ * const pattern: PatternConfig = {
+ *   variant: 'pattern',
+ *   columns: [100, '200px', '1fr'],
+ *   gap: 2
+ * }
+ *
+ * // Responsive pattern with mixed units
+ * const responsive: PatternConfig = {
+ *   variant: 'pattern',
+ *   columns: ['20%', '1fr', '200px'],
+ *   gap: 2
+ * }
+ * ```
+ */
+export type PatternConfig = BaseGuideConfig & {
+    /** Identifies this as a pattern-based configuration */
+    variant: 'pattern';
+    /** Array of column widths that repeat */
+    columns: GuideColumnsPattern;
+    /** Not applicable in pattern mode */
+    columnWidth?: never;
+};
+/**
+ * Fixed-column grid configuration.
+ * Specifies exact number of equal-width columns.
+ *
+ * @example
+ * ```ts
+ * // Basic 12-column grid
+ * const grid: FixedConfig = {
+ *   variant: 'fixed',
+ *   columns: 12,
+ *   gap: 2
+ * }
+ *
+ * // Fixed-width columns
+ * const fixed: FixedConfig = {
+ *   variant: 'fixed',
+ *   columns: 6,
+ *   columnWidth: '160px',
+ *   gap: 2
+ * }
+ * ```
+ */
+export type FixedConfig = BaseGuideConfig & {
+    /** Identifies this as a fixed-column configuration */
+    variant: 'fixed';
+    /** Number of columns to create */
+    columns: number;
+    /** Optional fixed width for all columns */
+    columnWidth?: React.CSSProperties['width'];
+};
+/**
+ * Auto-calculated grid configuration.
+ * Creates as many columns as will fit given a column width.
+ *
+ * @example
+ * ```ts
+ * // Auto-fit columns of 200px
+ * const auto: AutoConfig = {
+ *   variant: 'auto',
+ *   columnWidth: '200px',
+ *   gap: 2
+ * }
+ *
+ * // Responsive columns with minimum width
+ * const responsive: AutoConfig = {
+ *   variant: 'auto',
+ *   columnWidth: 'minmax(200px, 1fr)',
+ *   gap: 2
+ * }
+ * ```
+ */
+export type AutoConfig = BaseGuideConfig & {
+    /** Identifies this as an auto-calculated configuration */
+    variant: 'auto';
+    /** Desired width for each column */
+    columnWidth: React.CSSProperties['columnWidth'];
+    /** Not applicable in auto mode */
+    columns?: never;
+};
+/**
+ * Simple line-based guide configuration.
+ * Creates evenly-spaced vertical lines.
+ *
+ * @example
+ * ```ts
+ * // Basic line guide
+ * const lines: LineConfig = {
+ *   variant: 'line',
+ *   gap: 1
+ * }
+ *
+ * // Custom-spaced lines
+ * const wideLines: LineConfig = {
+ *   variant: 'line',
+ *   gap: 4,
+ *   base: 8
+ * }
+ * ```
+ */
+export type LineConfig = BaseGuideConfig & {
+    /** Optional variant identifier (defaults to 'line') */
+    variant?: 'line';
+    /** Not applicable in line mode */
+    columns?: never;
+    /** Not applicable in line mode */
+    columnWidth?: never;
+};
+export {};

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

@@ -0,0 +1,82 @@
+/**
+ * @file validation.ts
+ * @description Validation utilities for Guide component configurations
+ * @module baseline-kit/components/Guide/validation
+ */
+import { GridAlignment, GuideColumnsPattern, GuideColumnValue, GuideConfig } from '@components';
+/**
+ * Validates individual grid column values.
+ *
+ * @example
+ * ```ts
+ * isValidGuideColumnValue(100)     // true
+ * isValidGuideColumnValue('100px') // true
+ * isValidGuideColumnValue('auto')  // true
+ * isValidGuideColumnValue('foo')   // false
+ * ```
+ */
+export declare const isValidGuideColumnValue: (value: unknown) => value is GuideColumnValue;
+/**
+ * Validates an array of column values as a grid pattern.
+ *
+ * @example
+ * ```ts
+ * isValidGuidePattern(['100px', '1fr'])     // true
+ * isValidGuidePattern([100, 200])           // true
+ * isValidGuidePattern(['invalid'])          // false
+ * isValidGuidePattern([])                   // false
+ * ```
+ */
+export declare const isValidGuidePattern: (pattern: unknown) => pattern is GuideColumnsPattern;
+/**
+ * Validates CSS grid values against supported units.
+ *
+ * @example
+ * ```ts
+ * isGuideValue('100px')   // true
+ * isGuideValue('2rem')    // true
+ * isGuideValue('foo')     // false
+ * ```
+ */
+export declare const isGuideValue: (value: unknown) => boolean;
+/**
+ * Validates grid alignment values.
+ *
+ * @example
+ * ```ts
+ * isGuideAlignment('start')   // true
+ * isGuideAlignment('center')  // true
+ * isGuideAlignment('foo')     // false
+ * ```
+ */
+export declare const isGuideAlignment: (value: unknown) => value is GridAlignment;
+/**
+ * Validates line-based guide configurations.
+ *
+ * @example
+ * ```ts
+ * isGuideLineConfig({ variant: 'line' })           // true
+ * isGuideLineConfig({ variant: 'pattern' })        // false
+ * ```
+ */
+export declare const isGuideLineConfig: (config: unknown) => config is GuideConfig;
+/**
+ * Validates column-based guide configurations.
+ *
+ * @example
+ * ```ts
+ * isGuideColumnConfig({ columns: 12 })             // true
+ * isGuideColumnConfig({ variant: 'line' })         // false
+ * ```
+ */
+export declare const isGuideColumnConfig: (config: unknown) => config is GuideConfig;
+/**
+ * Validates auto-calculated guide configurations.
+ *
+ * @example
+ * ```ts
+ * isAutoCalculatedGuide({ columnWidth: '200px' })  // true
+ * isAutoCalculatedGuide({ columns: 12 })           // false
+ * ```
+ */
+export declare const isAutoCalculatedGuide: (config: unknown) => config is GuideConfig;

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

@@ -0,0 +1,69 @@
+/**
+ * @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 { ComponentsProps, Variant } from '../types';
+export type LayoutProps = {
+    /**
+     * Grid column definition. Supports:
+     * - Number: Equal columns (3 → repeat(3, 1fr))
+     * - String: Raw template ("1fr auto 200px")
+     * - Array: Mixed values ([100, '1fr'] → "100px 1fr")
+     */
+    columns?: number | string | Array<number | string>;
+    /** Grid row definition (same format as columns) */
+    rows?: number | string | Array<number | string>;
+    /** Controls item alignment along column axis */
+    justifyItems?: React.CSSProperties['justifyItems'];
+    /** Controls item alignment along row axis */
+    alignItems?: React.CSSProperties['alignItems'];
+    /** Controls content distribution along row axis */
+    justifyContent?: React.CSSProperties['justifyContent'];
+    /** Controls content distribution along column axis */
+    alignContent?: React.CSSProperties['alignContent'];
+    /** Custom measurement indicator renderer */
+    indicatorNode?: IndicatorNode;
+    /** Visual style in debug mode */
+    variant?: Variant;
+    children?: React.ReactNode;
+} & ComponentsProps & Gaps;
+/**
+ * A grid-based layout component with baseline alignment and responsive columns.
+ *
+ * @remarks
+ * Layout provides a CSS Grid container that:
+ * - Supports flexible column definitions
+ * - Maintains baseline grid alignment
+ * - Includes gap management
+ * - Offers comprehensive alignment controls
+ * - Provides debug overlays for visual verification
+ *
+ * When no explicit dimensions are provided, Layout defaults to "fit-content"
+ * for both width and height.
+ *
+ * @example
+ * ```tsx
+ * // Basic equal columns
+ * <Layout columns={3} gap={16}>
+ *   <div>Column 1</div>
+ *   <div>Column 2</div>
+ *   <div>Column 3</div>
+ * </Layout>
+ *
+ * // Mixed column widths with alignment
+ * <Layout
+ *   columns={['200px', '1fr', '2fr']}
+ *   gap={24}
+ *   alignItems="center"
+ *   justifyContent="space-between"
+ * >
+ *   <div>Fixed</div>
+ *   <div>Flexible</div>
+ *   <div>Double width</div>
+ * </Layout>
+ * ```
+ */
+export declare const Layout: React.NamedExoticComponent<LayoutProps>;

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

@@ -0,0 +1,10 @@
+/**
+ * @file Layout Component Entry (components/Layout/index.ts)
+ * @description Grid-based layout component with baseline alignment
+ * @module baseline-kit/components/Layout
+ *
+ * @remarks
+ * Provides CSS Grid functionality with built-in baseline grid
+ * alignment and debugging features.
+ */
+export * from './Layout';