baseline-kit 5.0.0 → 5.2.0

package/dist/README.md

@@ -1,468 +0,0 @@
-# Baseline Kit
-
-![Build Status](https://img.shields.io/github/actions/workflow/status/dnvt/baseline-kit/test.yml)
-![npm version](https://img.shields.io/npm/v/baseline-kit)
-![License](https://img.shields.io/github/license/dnvt/baseline-kit)
-
-Baseline Kit is a lightweight development tool for visualizing and debugging grid systems and spacing in React applications. It provides configurable overlays for both column-based and baseline grids, spacing primitives, and theme-aware configuration—all optimized for performance and built with TypeScript. The library is based on the "Padded Grid" concept, originally explored in [this article](http://medium.com/design-bootcamp/the-padded-grid-a-designers-hack-to-achieve-baseline-fit-fc40d022bc84) on achieving perfect baseline alignment in digital layouts.
-
-![Demo visual](kit.png)
-
-## Table of Contents
-  - [Features](#features)
-  - [Requirements](#requirements)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [Core Concepts](#core-concepts)
-    - [Base Unit](#base-unit)
-    - [Spacing Values](#spacing-values)
-    - [Grid Snapping](#grid-snapping)
-    - [Debugging Modes](#debugging-modes)
-  - [Components](#components)
-    - [Component Hierarchy](#component-hierarchy)
-    - [Key Components](#key-components)
-      - [Config](#config)
-      - [Baseline](#baseline)
-      - [Guide](#guide)
-      - [Box](#box)
-  - [Theme System](#theme-system)
-    - [CSS Import Options](#css-import-options)
-    - [Theme Options](#theme-options)
-    - [Theme Variables Reference](#theme-variables-reference)
-  - [Browser Support](#browser-support)
-  - [React 19 Features](#react-19-features)
-  - [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
-    - [SSR-Friendly Design](#ssr-friendly-design)
-    - [SSR Mode Prop](#ssr-mode-prop)
-  - [Development](#development)
-  - [Performance Features](#performance-features)
-  - [Contributing](#contributing)
-  - [License](#license)
-
-## Features
-
-- 📏 **Baseline Grid:** Core system for maintaining vertical rhythm and consistent spacing across your layouts
-- 🎯 **Column Grid Guide:** Customizable overlay system for visualizing column-based layouts and alignment
-- 📦 **Box Component:** Basic container with configurable spacing that snaps to the baseline grid
-- 🧱 **Padder & Spacer:** Spacing primitives with optional baseline snapping
-- 🎨 **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
-# Using npm
-npm install baseline-kit
-
-# Using yarn
-yarn add baseline-kit
-
-# Using pnpm
-pnpm add baseline-kit
-```
-
-After installation, import the smallest entry point that matches your use case.
-For a development grid overlay, use the guide-only React and CSS subpaths:
-
-```tsx
-import 'baseline-kit/styles/guide'
-import { Config, Guide } from 'baseline-kit/guide'
-```
-
-For frameworks like Remix that use URL imports in a links function:
-
-```tsx
-export const links = () => [
-  { rel: 'stylesheet', href: 'baseline-kit/styles/guide' },
-]
-```
-
-For the full component set, import the root package and root component styles:
-
-```tsx
-import 'baseline-kit/styles'
-import 'baseline-kit/theme'
-import { Config, Guide, Baseline, Box } from 'baseline-kit'
-```
-
-If you prefer a single CSS file for every component plus the theme:
-
-```tsx
-import 'baseline-kit/styles/full'
-
-// For Remix:
-export const links = () => [
-  { rel: 'stylesheet', href: 'baseline-kit/styles/full' },
-]
-```
-
-The browser reset is not included by default. Import `baseline-kit/reset` or
-`baseline-kit/styles/reset` only when you want Baseline Kit to provide one.
-
-Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.
-
-## Quick Start
-
-```tsx
-import React from 'react'
-import { Config, Guide, Baseline, Box } from 'baseline-kit'
-
-function App() {
-  const isDev = process.env.NODE_ENV === 'development'
-  const debugging = isDev ? 'visible' : 'hidden'
-
-  return (
-    <Config
-      base={8}
-      baseline={{ debugging }}
-      box={{ debugging }}
-      guide={{ debugging }}
-      spacer={{ debugging }}
-    >
-      {/* Baseline Grid for typography alignment */}
-      <Baseline
-        height="100vh"
-        debugging="visible"
-      />
-
-      {/* Column Grid Guide */}
-      <Guide
-        variant="pattern"
-        columns={['100px', '200px', '100px']}
-        gap={16}
-        align="center"
-        width="1200px"
-      />
-
-      {/* Box with baseline alignment */}
-      <Box
-        block={[2, 5]}
-        debugging="visible"
-      >
-        <h1>Content Aligned to the Grid</h1>
-      </Box>
-
-      <main>Your main content goes here...</main>
-    </Config>
-  )
-}
-```
-
-## Core Concepts
-
-### Base Unit
-
-The base unit is the foundation of Baseline Kit's spacing system. All measurements are calculated as multiples of this
-unit:
-
-```tsx
-<Config base={8}>     // Sets 8px as the base unit
-  <Padder
-    block={17}        // Will be rounded to 16px (2 * base)
-    inline={22}       // Will be rounded to 24px (3 * base)
-  >
-    {/* Content automatically aligned to the 8px grid */}
-  </Padder>
-</Config>
-```
-
-### Spacing Values
-
-Spacing props (`block`, `inline`, `gap`) accept values in three formats:
-
-```
-// Single number (applies to both sides)
-block={16}                  // 16px top and bottom
-
-// Array [start, end]
-block={[2, 3]}                // 2px top, 3px bottom
-
-// Object with explicit values
-block={{ start: 2, end: 3 }}  // Same as above
-```
-
-### Grid Snapping
-
-Components automatically adjust their spacing to maintain baseline grid alignment:
-
-- **Box**: Adjusts bottom padding to ensure total height aligns with base unit
-- **Padder**: Snaps padded content to baseline-aligned multiples of the base unit
-
-### Debugging Modes
-
-Three modes are available for development and testing:
-
-```tsx
-debugging = "visible"        // Shows all grid lines and measurements
-debugging = "hidden"         // Elements exist but are invisible
-debugging = "none"           // Removes debug elements entirely
-```
-
-## Components
-
-### Component Hierarchy
-
-#### 1. Spacing primitives
-
-- **`Box`** Basic container that snaps its height to the baseline grid
-- **`Padder`** Padding wrapper that snaps padded content to baseline multiples
-- **`Spacer`** Fixed-size spacer with optional measurement indicator overlay
-
-#### 2. Debug overlays
-
-- **`Baseline`** Horizontal baseline-grid overlay
-- **`Guide`** Column-grid overlay (line / pattern / fixed / auto variants)
-
-#### 3. Configuration
-
-- **`Config`** Theme and settings provider (base unit, colors, debug modes)
-
-### Key Components
-
-#### Config
-
-```tsx
-<Config
-  base={8}                         // Base unit for calculations
-  baseline={{ debugging }}         // Baseline grid visibility
-  guide={{ debugging }}            // Guide customization
->
-  {children}
-</Config>
-```
-
-#### Baseline
-
-```tsx
-<Baseline
-  height="100vh"          // Overlay height
-  variant="line"          // "line" or "flat"
-  debugging="visible"     // Show the grid overlay
-/>
-```
-
-#### Guide
-
-```tsx
-<Guide
-  variant="pattern"                     // "line", "pattern", "fixed", or "auto"
-  columns={['100px', '1fr', '100px']}   // Column definition
-  gap={8}                               // Gap value
-  width="1200px"                        // Container width
-/>
-```
-
-#### Box
-
-```tsx
-<Box
-  block={[2, 5]}         // Vertical padding in base units
-  span={2}               // Grid column span when placed in a CSS grid parent
-  snapping="height"      // "none", "height", or "clamp"
->
-  <p>Content aligned to baseline grid</p>
-</Box>
-```
-
-## Theme System
-
-Baseline Kit comes with a flexible CSS structure and theming system:
-
-1. `guide.css` - Guide-only overlay styles (imported via `baseline-kit/styles/guide`)
-2. `styles.css` - Root component styles and base variables (imported via `baseline-kit/styles`)
-3. `theme.css` - Color variables and theming with automatic dark mode support (imported via `baseline-kit/theme`)
-4. `reset.css` - Optional browser reset (imported via `baseline-kit/reset` or `baseline-kit/styles/reset`)
-5. `baseline-kit.css` - Combined root component styles and theme (imported via `baseline-kit/styles/full`)
-
-### CSS Import Options
-
-Baseline Kit gives you flexibility in how you include the styles:
-
-```tsx
-// Guide-only overlay styles
-import 'baseline-kit/styles/guide'
-
-// Root component styles and theme separately
-import 'baseline-kit/styles'
-import 'baseline-kit/theme'
-
-// Root component styles and theme in one file
-import 'baseline-kit/styles/full'
-
-// Optional reset
-import 'baseline-kit/reset'
-```
-
-### Theme Options
-
-You now have four options for using the theme system:
-
-#### 1. Use the Built-in Theme (with automatic dark mode)
-
-```tsx
-import 'baseline-kit/theme' // Default theme with light/dark mode support
-```
-
-#### 2. Use Specific Theme Variants
-
-```tsx
-// Use only the light theme (no dark mode)
-import 'baseline-kit/theme/default'
-
-// Use only the dark theme
-import 'baseline-kit/theme/dark'
-
-// Example: Apply dark theme regardless of system preference
-import 'baseline-kit/styles'
-import 'baseline-kit/theme/dark'
-```
-
-#### 3. Create a Custom Theme
-
-You can use the tokens template as a starting point:
-
-```tsx
-// First check the token template to see available variables
-import 'baseline-kit/theme/tokens' // Just for reference (contains no values)
-```
-
-Then create your own custom theme 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);
-  }
-}
-```
-
-Then import your custom theme:
-
-```tsx
-import 'baseline-kit/styles' // Required component styles
-import './path/to/yourCustomTheme.css' // Your custom theme
-```
-
-#### 4. Override via Config
-
-For minor adjustments, use the Config component:
-
-```tsx
-<Config
-  baseline={{
-    colors: {
-      line: 'rgba(255,0,0,0.1)',   // Custom red baseline lines
-      flat: 'rgba(255,0,0,0.05)',  // Custom red baseline backgrounds
-    }
-  }}
->
-  {/* Your components here */}
-</Config>
-```
-
-### Theme Variables Reference
-
-| 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 |
-| Spacer    | `--bk-spacer-color-[line/flat/text]-theme` | Colors for borders, backgrounds and text |
-| Padder    | `--bk-padder-color-theme` | Padder edge color |
-
-See the [tokens file](https://github.com/dnvt/baseline-kit/blob/main/dist/theme/tokens.css) for a complete list of available variables.
-
-## 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.
-For debug overlays such as `Guide` and `Baseline`, `ssrMode` keeps the simplified fallback markup to avoid client measurement and row/column rendering in SSR-sensitive paths.
-
-## Development
-
-```shell
-# Clone the repository
-git clone --recurse-submodules https://github.com/dnvt/baseline-kit.git
-
-# If you already cloned without submodules
-git submodule update --init --recursive
-
-# Install dependencies
-bun install
-
-# Start development server
-bun run dev
-
-# Run tests
-bun run test
-```
-
-The `.maestro/source` directory is a workflow submodule. Generated local
-workflow surfaces such as `.claude/`, `maestro/`, `progress/`, and `plans/` are
-ignored. Do not run the Maestro layout migration until the submodule source is
-mounted at `.maestro/source` and the migration plan has been reviewed.
-
-## Performance Features
-
-- Virtualizes large grid overlays
-- Client-side only rendering for dynamic components
-- Optimized resize event handling
-- Optimizes re-renders using React.memo and useMemo
-- Supports tree-shaking for minimal bundle size
-
-## Contributing
-
-Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
-
-## License
-
-MIT © [François Denavaut](https://github.com/dnvt)

package/dist/core/src/config/defaults.d.ts

@@ -1,2 +0,0 @@
-import type { ConfigSchema } from './schema';
-export declare const DEFAULT_CONFIG: ConfigSchema;

package/dist/core/src/config/index.d.ts

@@ -1,3 +0,0 @@
-export type { ConfigSchema } from './schema';
-export { DEFAULT_CONFIG } from './defaults';
-export { mergeConfig, createCSSVariables } from './merge';

package/dist/core/src/config/merge.d.ts

@@ -1,21 +0,0 @@
-import type { ConfigSchema } from './schema';
-type MergeConfigParams = {
-    parentConfig: ConfigSchema;
-    base?: number;
-    baseline?: Partial<ConfigSchema['baseline']>;
-    guide?: Partial<ConfigSchema['guide']>;
-    spacer?: Partial<ConfigSchema['spacer']>;
-    box?: Partial<ConfigSchema['box']>;
-    padder?: Partial<ConfigSchema['padder']>;
-};
-export declare const mergeConfig: (params: MergeConfigParams) => ConfigSchema;
-type CSSVariablesParams = {
-    base: number;
-    baseline: ConfigSchema['baseline'];
-    guide: ConfigSchema['guide'];
-    spacer: ConfigSchema['spacer'];
-    box: ConfigSchema['box'];
-    padder: ConfigSchema['padder'];
-};
-export declare const createCSSVariables: (params: CSSVariablesParams) => Record<string, string>;
-export {};

package/dist/core/src/config/schema.d.ts

@@ -1,33 +0,0 @@
-import type { GuideVariant, BaselineVariant, Variant, DebuggingMode } from '../types';
-type DebugColors = {
-    line: string;
-    flat: string;
-    text: string;
-};
-export type ConfigSchema = {
-    base: number;
-    baseline: {
-        variant: BaselineVariant;
-        debugging: DebuggingMode;
-        colors: Record<BaselineVariant, string>;
-    };
-    guide: {
-        variant: GuideVariant;
-        debugging: DebuggingMode;
-        colors: Record<GuideVariant, string>;
-    };
-    spacer: {
-        variant: Variant;
-        debugging: DebuggingMode;
-        colors: DebugColors;
-    };
-    box: {
-        debugging: DebuggingMode;
-        colors: DebugColors;
-    };
-    padder: {
-        debugging: DebuggingMode;
-        color: string;
-    };
-};
-export {};

package/dist/core/src/descriptors/baseline.d.ts

@@ -1,26 +0,0 @@
-import type { BaselineVariant } from '../types';
-export interface BaselineDescriptorParams {
-    base: number;
-    colors: Record<BaselineVariant, string>;
-    variant: BaselineVariant;
-    width?: number | string;
-    height?: number | string;
-    color?: string;
-    containerWidth: number;
-    containerHeight: number;
-    spacing: Record<string, unknown>;
-    isVisible: boolean;
-}
-export interface BaselineDescriptor {
-    containerStyle: Record<string, string>;
-    rowCount: number;
-    getRowStyle: (index: number) => Record<string, string>;
-    padding: string | undefined;
-    isVisible: boolean;
-    classTokens: string[];
-}
-/**
- * Computes all styles and data needed to render a Baseline component.
- * Pure function — framework-agnostic.
- */
-export declare function createBaselineDescriptor(params: BaselineDescriptorParams): BaselineDescriptor;

package/dist/core/src/descriptors/box.d.ts

@@ -1,20 +0,0 @@
-export interface BoxDescriptorParams {
-    base: number;
-    lineColor: string;
-    width?: number | string;
-    height?: number | string;
-    span?: number;
-    colSpan?: number;
-    rowSpan?: number;
-    isVisible: boolean;
-}
-export interface BoxDescriptor {
-    boxStyle: Record<string, string>;
-    gridSpanStyle: Record<string, string>;
-    classTokens: string[];
-}
-/**
- * Computes styles needed to render a Box component.
- * Pure function — framework-agnostic.
- */
-export declare function createBoxDescriptor(params: BoxDescriptorParams): BoxDescriptor;

package/dist/core/src/descriptors/guide.d.ts

@@ -1,44 +0,0 @@
-import type { GuideVariant, GuideConfig } from '../types';
-export interface GuideDescriptorParams {
-    base: number;
-    colors: Record<GuideVariant, string>;
-    variant: GuideVariant;
-    align: string;
-    width?: number | string;
-    height?: number | string;
-    columnWidth?: number | string;
-    maxWidth?: number | string;
-    color?: string;
-    /** Pre-computed guide template result (from useGuide or calculateGuideTemplate) */
-    template: string;
-    columnsCount: number;
-    calculatedGap: number;
-    isVisible: boolean;
-}
-export interface GuideDescriptor {
-    containerStyle: Record<string, string>;
-    columnColor: string;
-    columnsCount: number;
-    calculatedGap: number;
-    template: string;
-    isVisible: boolean;
-    isLineVariant: boolean;
-    classTokens: string[];
-}
-export interface GuideConfigParams {
-    variant: GuideVariant;
-    base: number;
-    gap: number;
-    columns?: number | readonly (string | number | undefined | 'auto')[];
-    columnWidth?: number | string;
-}
-/**
- * Creates a GuideConfig from component props.
- * Pure function — no React or DOM dependency.
- */
-export declare function createGuideConfig({ variant, base, gap, columns, columnWidth, }: GuideConfigParams): GuideConfig;
-/**
- * Computes all styles and data needed to render a Guide component.
- * Pure function — framework-agnostic.
- */
-export declare function createGuideDescriptor(params: GuideDescriptorParams): GuideDescriptor;

package/dist/core/src/descriptors/index.d.ts

@@ -1,5 +0,0 @@
-export * from './guide';
-export * from './baseline';
-export * from './box';
-export * from './spacer';
-export * from './padder';

package/dist/core/src/descriptors/padder.d.ts

@@ -1,19 +0,0 @@
-import type { Padding } from '../types';
-export interface PadderDescriptorParams {
-    base: number;
-    color: string;
-    width?: number | string;
-    height?: number | string;
-    padding: Padding;
-    enableSpacers: boolean;
-    isVisible: boolean;
-}
-export interface PadderDescriptor {
-    containerStyle: Record<string, string>;
-    classTokens: string[];
-}
-/**
- * Computes styles needed to render a Padder component.
- * Pure function — framework-agnostic.
- */
-export declare function createPadderDescriptor(params: PadderDescriptorParams): PadderDescriptor;

package/dist/core/src/descriptors/spacer.d.ts

@@ -1,24 +0,0 @@
-export interface SpacerDescriptorParams {
-    base: number;
-    colors: {
-        line: string;
-        flat: string;
-        text: string;
-    };
-    width?: number | string;
-    height?: number | string;
-    color?: string;
-    variant: string;
-    isVisible: boolean;
-}
-export interface SpacerDescriptor {
-    style: Record<string, string>;
-    normWidth: number;
-    normHeight: number;
-    classTokens: string[];
-}
-/**
- * Computes styles needed to render a Spacer component.
- * Pure function — framework-agnostic.
- */
-export declare function createSpacerDescriptor(params: SpacerDescriptorParams): SpacerDescriptor;

package/dist/core/src/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * @baseline-kit/core
- * Pure TypeScript core: types, utilities, config, validation, and descriptors
- * Zero dependencies — works in any JavaScript runtime
- */
-export * from './types';
-export * from './config';
-export * from './utils';
-export * from './validation';
-export * from './descriptors';