baseline-kit 2.0.1 → 2.1.0

package/dist/README.md

@@ -1,10 +1,10 @@
 # Baseline Kit
 
-Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React
+Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React 19
 applications. It provides configurable overlays for both column-based and baseline grids, flexible layout components,
 and theme-aware configuration—all optimized for performance and built with TypeScript.
 
-![Demo visual](demo/padded-demo.png)
+![Demo visual](kit.png)
 
 ## Features
 
@@ -15,6 +15,11 @@ and theme-aware configuration—all optimized for performance and built with Typ
 - 📐 **Stack Component:** Flex-based container that maintains consistent spacing and baseline alignment
 - 🎨 **Theme System:** Customizable colors and debug visuals through a centralized configuration
 
+## Requirements
+
+- **React 19**: Baseline Kit is built for React 19 and uses the latest React features like the `use` hook
+- **Modern Browsers**: Supporting the latest CSS features
+
 ## Installation
 
 ```shell
@@ -28,18 +33,21 @@ yarn add baseline-kit
 pnpm add baseline-kit
 ```
 
-### TypeScript Support
+After installation, import both the styles and theme in your application:
+
+```tsx
+// Import in your main entry file (e.g., index.js, App.js)
+import 'baseline-kit/styles';  // Required core styles
+import 'baseline-kit/theme';   // Recommended theme (or use your own)
+```
 
-Baseline Kit is written in TypeScript and includes built-in type definitions. No additional packages are required.
+Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.
 
 ## Quick Start
 
-Basic setup with debugging enabled during development:
-
 ```tsx
 import React from 'react'
 import { Config, Guide, Baseline, Box } from 'baseline-kit'
-import 'baseline-kit/styles.css'
 
 function App() {
   const isDev = process.env.NODE_ENV === 'development'
@@ -97,13 +105,6 @@ unit:
   >
     {/* Content automatically aligned to the 8px grid */}
   </Layout>
-
-  <Stack
-    block={[17, 25]}  // Top: 16px, Bottom: 24px
-    inline={22}       // Left/Right: 24px
-  >
-    {/* Padding automatically adjusted to base unit multiples */}
-  </Stack>
 </Config>
 ```
 
@@ -113,7 +114,7 @@ Spacing props (`block`, `inline`, `gap`) accept values in three formats:
 
 ```
 // Single number (applies to both sides)
-block={16px}                  // 16px top and bottom
+block={16}                  // 16px top and bottom
 
 // Array [start, end]
 block={[2, 3]}                // 2px top, 3px bottom
@@ -159,128 +160,172 @@ debugging = "none"           // Removes debug elements entirely
 #### 3. Configuration
 
 - **`Config`** Theme and settings provider
-- **`Padder`** Internal spacing utility
 
-### Config
+### Key Components
 
-The Config component provides theme and debugging settings to all child components.
+#### Config
 
 ```tsx
 <Config
   base={8}                         // Base unit for calculations
   baseline={{ debugging }}         // Baseline grid visibility
-  guide={{                         // Guide customization
-    debugging,
-    colors: {
-      line: 'rgba(0,0,255,0.1)'
-    }
-  }}
+  guide={{ debugging }}            // Guide customization
 >
   {children}
 </Config>
 ```
 
-### Baseline
+#### Baseline
 
 ```tsx
 <Baseline
-  base={8}                // Base unit (defaults to Config value)
   height="100vh"          // Overlay height
   variant="line"          // "line" or "flat"
   debugging="visible"     // Show the grid overlay
 />
 ```
 
-### Guide
+#### Guide
 
 ```tsx
 <Guide
-  variant="pattern"                          // "line", "pattern", "fixed", or "auto"
-  columns={['100px', '1fr', '100px']}        // Column definition
-  gap={8}                                    // Gap value
-  align="center"                             // "start", "center", or "end"
-  width="1200px"                             // Container width
-  debugging="visible"                        // Show grid overlay
+  variant="pattern"                     // "line", "pattern", "fixed", or "auto"
+  columns={['100px', '1fr', '100px']}   // Column definition
+  gap={8}                               // Gap value
+  width="1200px"                        // Container width
 />
 ```
 
-### Box
+#### Box
 
 ```tsx
 <Box
-  block={[2, 5]}         // Vertical padding in base units (auto-adjusted for baseline)
+  block={[2, 5]}         // Vertical padding in base units
   span={2}               // Grid column span when used in Layout
   snapping="height"      // "none", "height", or "clamp"
-  debugging="visible"    // Show alignment guides
 >
   <p>Content aligned to baseline grid</p>
 </Box>
 ```
 
-### Stack
+## Theme System
+
+Baseline Kit comes with two CSS files:
+
+1. `styles.css` - Contains the core component styles required for functionality
+2. `theme.css` - Contains color variables and theming (optional but recommended)
+
+### Theme Options
+
+You have three options for using the theme system:
+
+#### 1. Use the Built-in Theme
 
 ```tsx
-<Stack
-  direction="column"     // "row" or "column"
-  block={[8, 24]}        // Vertical padding (auto-snapping)
-  inline={16}            // Horizontal padding (auto-snapping)
-  gap={16}               // Gap value
-  justify="center"       // Flex justify-content
-  align="center"         // Flex align-items
-  debugging="visible"    // Show alignment guides
->
-  <Box>Item 1</Box>
-  <Box>Item 2</Box>
-</Stack>
+import 'baseline-kit/theme';  // Default theme with light/dark mode support
 ```
 
-### Layout
+#### 2. Create a Custom Theme
 
-```tsx
-<Layout
-  columns={3}            // Number of columns or pattern array
-  gap={16}               // Gap value
-  block={16}             // Vertical padding (auto-snapping)
-  inline={8}             // Horizontal padding (auto-snapping)
-  debugging="visible"    // Show grid guides
->
-  <Box span={2}>Wide content</Box>
-  <Box>Regular content</Box>
-</Layout>
+Create your own theme.css file:
+
+```css
+/* yourCustomTheme.css */
+:root {
+  /* Component-specific colors */
+  --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.15);
+  --bk-baseline-color-flat-theme: hsla(270, 100%, 60%, 0.2);
+  /* Add other component colors as needed */
+}
+
+/* Optional dark mode support */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bk-baseline-color-line-theme: hsla(210, 100%, 50%, 0.2);
+  }
+}
 ```
 
-## Theme System
+Then import your custom theme:
+
+```tsx
+import 'baseline-kit/styles';  // Required core styles
+import './path/to/yourCustomTheme.css';  // Your custom theme
+```
 
-### Color Customization
+#### 3. Override via Config
 
-The theme system allows customization of debugging visuals through the Config component:
+For minor adjustments, use the Config component:
 
 ```tsx
 <Config
-  base={8}
-  guide={{
-    colors: {
-      line: 'rgba(0,0,255,0.1)',
-      pattern: 'rgba(0,0,255,0.05)',
-      auto: 'rgba(0,0,255,0.05)',
-      fixed: 'rgba(0,0,255,0.05)'
-    }
-  }}
   baseline={{
     colors: {
-      line: 'rgba(255,0,0,0.1)',
-      flat: 'rgba(255,0,0,0.05)'
+      line: 'rgba(255,0,0,0.1)',   // Custom red baseline lines
+      flat: 'rgba(255,0,0,0.05)',  // Custom red baseline backgrounds
     }
   }}
 >
-  {children}
+  {/* Your components here */}
 </Config>
 ```
 
-The library uses CSS custom properties for colors, which automatically respect the user's system dark mode preferences
-through CSS media queries. No additional configuration is required.
+### Theme Variables Reference
 
-## Development Setup
+| Component | Variable Pattern | Purpose |
+|-----------|-----------------|---------|
+| Baseline  | `--bk-baseline-color-[line/flat]-theme` | Colors for lines and backgrounds |
+| Guide     | `--bk-guide-color-[line/pattern/auto/fixed]-theme` | Colors for different guide variants |
+| Box       | `--bk-box-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+| Stack     | `--bk-stack-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+| Layout    | `--bk-layout-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+| Spacer    | `--bk-spacer-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
+
+See the [default theme file](https://github.com/dnvt/baseline-kit/blob/main/dist/theme.css) for a complete example.
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires CSS Grid Layout support and CSS Custom Properties
+- Falls back gracefully in unsupported browsers
+
+## React 19 Features
+
+Baseline Kit leverages React 19's latest features:
+
+- **`use` Hook**: Replaces `useContext` for better performance and cleaner code
+- **Streamlined Context API**: Uses the simplified Context Provider syntax
+- **JSX Transform**: Takes advantage of the mandatory JSX transform in React 19
+
+These modern features allow for cleaner code and better performance, but require React 19.
+
+## Server-Side Rendering (SSR)
+
+Baseline Kit is fully compatible with React's Server-Side Rendering in frameworks like Next.js, Remix, and other React Router-based applications.
+
+### SSR-Friendly Design
+
+Components are designed to:
+- Provide consistent rendering between server and client
+- Avoid hydration mismatches by using deterministic initial values
+- Progressively enhance with client-side measurements after hydration
+- Work with frameworks that use streaming SSR
+
+### SSR Mode Prop
+
+Components accept an `ssrMode` prop to explicitly optimize for server rendering:
+
+```tsx
+<Baseline
+  height="100vh"
+  ssrMode={true}
+  debugging="visible"
+/>
+```
+
+With `ssrMode` enabled, components use simplified rendering during SSR and initial hydration, then enhance with full features after client-side hydration completes.
+
+## Development
 
 ```shell
 # Clone the repository
@@ -294,38 +339,17 @@ bun run dev
 
 # Run tests
 bun run test
-
-# Build package
-bun run build
 ```
 
-## Server-Side Rendering
+## Performance Features
 
-Baseline Kit is compatible with SSR frameworks like Next.js and Gatsby. The overlay components automatically handle
-hydration mismatches.
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires CSS Grid Layout support
-- Requires CSS Custom Properties (CSS Variables)
-- Falls back gracefully in unsupported browsers
-
-## Performance Considerations
-
-- Uses requestAnimationFrame for smooth animations
 - Virtualizes large grid overlays
 - Optimizes re-renders using React.memo
 - Supports tree-shaking for minimal bundle size
 
 ## Contributing
 
-Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines on:
-
-- Development setup
-- Code style
-- Testing requirements
-- Pull request process
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
 ## License
 

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

@@ -1,8 +1,3 @@
-/**
- * @file Baseline Component
- * @description Horizontal grid overlay for baseline alignment
- * @module components
- */
 import * as React from 'react';
 import { ComponentsProps } from '@components';
 import { Variant } from '../types';
@@ -16,7 +11,33 @@ export type BaselineProps = {
     height?: number | string;
     /** Base unit for measurements (defaults to theme value) */
     base?: number;
+    /** Color override for grid lines */
+    color?: string;
+    /** Flag to enable SSR-compatible mode (simplified initial render) */
+    ssrMode?: boolean;
 } & ComponentsProps;
+/** Creates default baseline styles */
+export declare const createDefaultBaselineStyles: (base: number, lineColor: string, flatColor: string) => Record<string, string>;
+/** Create row styles for baseline lines */
+type RowStyleParams = {
+    /** Row index */
+    index: number;
+    /** Base unit for calculations */
+    base: number;
+    /** Baseline visual variant */
+    variant: BaselineVariant;
+    /** Selected color for the baseline */
+    chosenColor: string;
+    /** Theme line color */
+    lineColor: string;
+    /** Theme flat color */
+    flatColor: string;
+};
+/**
+ * Creates styles for an individual baseline row.
+ * Applies positioning and visual styling based on variant.
+ */
+export declare const createBaselineRowStyle: (params: RowStyleParams) => React.CSSProperties;
 /**
  * Renders horizontal guidelines for maintaining vertical rhythm and baseline alignment.
  *
@@ -47,3 +68,4 @@ export type BaselineProps = {
  * ```
  */
 export declare const Baseline: React.NamedExoticComponent<BaselineProps>;
+export {};

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

@@ -1,8 +1,3 @@
-/**
- * @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.
@@ -13,6 +8,29 @@ import * as React from 'react';
  * - `clamp`: Both height and spacing values snap to base unit multiples
  */
 export type SnappingMode = 'none' | 'height' | 'clamp';
+/**
+ * Creates default box styles with theme values.
+ * Sets CSS variables for width, height, base unit, and colors.
+ */
+export declare const createDefaultBoxStyles: (base: number, lineColor: string) => Record<string, string>;
+/** Parameters for creating box custom styles */
+type BoxCustomStylesParams = {
+    /** Width property for the box */
+    width?: React.CSSProperties['width'];
+    /** Height property for the box */
+    height?: React.CSSProperties['height'];
+    /** Base unit for measurements */
+    base: number;
+    /** Line color from theme */
+    lineColor: string;
+    /** Default styles for comparison */
+    defaultStyles: Record<string, string>;
+};
+/**
+ * Creates custom styles for the box.
+ * Combines all style properties and only applies changes when needed.
+ */
+export declare const createBoxCustomStyles: ({ width, height, base, lineColor, defaultStyles }: BoxCustomStylesParams) => React.CSSProperties;
 /**
  * A foundational container component that ensures consistent spacing and baseline alignment.
  *
@@ -52,6 +70,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;
@@ -60,3 +80,4 @@ export declare const Box: React.NamedExoticComponent<{
     height?: React.CSSProperties["height"];
     width?: React.CSSProperties["width"];
 } & import("..").SpacingProps & React.RefAttributes<HTMLDivElement>>;
+export {};

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.
@@ -87,8 +82,56 @@ type ConfigProps = {
     /** 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>;
+/** Parameters for creating CSS variables */
+type CSSVariablesParams = {
+    /** Base unit for spacing calculations */
+    base: number;
+    /** Baseline component configuration */
+    baseline: Config['baseline'];
+    /** Guide component configuration */
+    guide: Config['guide'];
+    /** Stack component configuration */
+    stack: Config['stack'];
+    /** Spacer component configuration */
+    spacer: Config['spacer'];
+    /** Layout component configuration */
+    layout: Config['layout'];
+    /** Box component configuration */
+    box: Config['box'];
+    /** Padder component configuration */
+    padder: Config['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: Config;
+    /** Base unit override */
+    base?: number;
+    /** Baseline component overrides */
+    baseline?: Partial<Config['baseline']>;
+    /** Guide component overrides */
+    guide?: Partial<Config['guide']>;
+    /** Spacer component overrides */
+    spacer?: Partial<Config['spacer']>;
+    /** Box component overrides */
+    box?: Partial<Config['box']>;
+    /** Stack component overrides */
+    stack?: Partial<Config['stack']>;
+    /** Layout component overrides */
+    layout?: Partial<Config['layout']>;
+    /** Padder component overrides */
+    padder?: Partial<Config['padder']>;
+};
+/**
+ * Merges parent config with overrides.
+ * Creates a new config object without mutating the parent.
+ */
+export declare const mergeConfig: (params: MergeConfigParams) => Config;
 /**
  * Configuration provider for baseline-kit components.
  *

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

@@ -1,20 +1,42 @@
-/**
- * @file Guide Component
- * @description Visual grid overlay component for alignment and debugging
- * @module components
- */
 import * as React from 'react';
 import { AutoConfig, FixedConfig, LineConfig, PatternConfig } from './types';
-import type { ComponentsProps } from '../types';
+import type { ComponentsProps, 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'];
+    /** Gutter width between columns */
+    gutterWidth?: 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'>;
+/** Parameters for creating a grid configuration */
+type GridConfigParams = {
+    variant: GuideVariant;
+    base: number;
+    gap: number;
+    columns?: number | readonly (string | number | undefined | 'auto')[];
+    columnWidth?: React.CSSProperties['width'];
+};
+/** Creates the appropriate grid configuration based on variant */
+export declare const createGridConfig: (params: GridConfigParams) => (PatternConfig | AutoConfig | FixedConfig | LineConfig);
+/** Creates default guide styles */
+export declare const createDefaultGuideStyles: (base: number, lineColor: string) => Record<string, string>;
 /**
  * A developer tool component that provides visual grid overlays for alignment.
  *
@@ -59,3 +81,4 @@ export type GuideProps = {
  * ```
  */
 export declare const Guide: React.NamedExoticComponent<GuideProps>;
+export {};

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,8 +25,24 @@ 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;
+/** Creates default layout styles with theme colors */
+export declare const createDefaultLayoutStyles: (colors: {
+    line: string;
+    flat: string;
+    text: string;
+}) => Record<string, string>;
+/** Parses grid template definitions into CSS grid-template values. */
+export declare const getGridTemplate: (prop?: number | string | Array<number | string>) => string;
+/** Creates grid gap styles */
+export declare const createGridGapStyles: (gap?: React.CSSProperties["gap"] | number, rowGap?: React.CSSProperties["rowGap"] | number, columnGap?: React.CSSProperties["columnGap"] | number) => Record<string, string>;
 /**
  * A grid-based layout component with baseline alignment and responsive columns.
  *
@@ -67,3 +80,4 @@ export type LayoutProps = {
  * ```
  */
 export declare const Layout: React.NamedExoticComponent<LayoutProps>;
+export {};

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