baseline-kit 2.0.1 → 3.0.0

package/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,42 @@ yarn add baseline-kit
 pnpm add baseline-kit
 ```
 
-### TypeScript Support
+After installation, import both the styles and theme in your application:
 
-Baseline Kit is written in TypeScript and includes built-in type definitions. No additional packages are required.
+```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)
+```
 
-## Quick Start
+For frameworks like Remix that use URL imports in a links function:
+
+```tsx
+export const links = () => [
+  { rel: "stylesheet", href: "baseline-kit/styles" },
+  { rel: "stylesheet", href: "baseline-kit/theme" }
+];
+```
+
+If you prefer a single CSS file that includes everything:
+
+```tsx
+// Alternative: Import everything in one file
+import 'baseline-kit/full';
+
+// For Remix:
+export const links = () => [
+  { rel: "stylesheet", href: "baseline-kit/full" }
+];
+```
+
+Baseline Kit is written in TypeScript and includes built-in type definitions—no additional packages required.
 
-Basic setup with debugging enabled during development:
+## Quick Start
 
 ```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 +126,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 +135,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 +181,207 @@ 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 a flexible CSS structure and theming system:
+
+1. `core.css` - Contains the core component styles required for functionality (imported via `baseline-kit/styles`)
+2. `theme.css` - Contains color variables and theming with automatic dark mode support (imported via `baseline-kit/theme`)
+3. `baseline-kit.css` - Combined file with both core and theme styles (imported via `baseline-kit/full`)
+
+### CSS Import Options
+
+Baseline Kit gives you flexibility in how you include the styles:
 
 ```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>
+// Option 1: Import core styles and theme separately (recommended)
+import 'baseline-kit/styles';
+import 'baseline-kit/theme';
+
+// Option 2: Import everything in one file
+import 'baseline-kit/full';
 ```
 
-### Layout
+### Theme Options
+
+You now have four options for using the theme system:
+
+#### 1. Use the Built-in Theme (with automatic dark mode)
 
 ```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>
+import 'baseline-kit/theme';  // Default theme with light/dark mode support
 ```
 
-## Theme System
+#### 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';
+```
 
-### Color Customization
+#### 3. Create a Custom Theme
 
-The theme system allows customization of debugging visuals through the Config component:
+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 core styles
+import './path/to/yourCustomTheme.css';  // Your custom theme
+```
+
+#### 4. Override via Config
+
+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,39 +395,94 @@ bun run dev
 
 # Run tests
 bun run test
-
-# Build package
-bun run build
 ```
 
-## Server-Side Rendering
-
-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
+## Performance Features
 
-- 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
 
-MIT © [François Denavaut](https://github.com/dnvt)
+MIT © [François Denavaut](https://github.com/dnvt)
+
+## Integration with Remix
+
+Baseline Kit is fully compatible with Remix. Follow these steps to integrate it into your Remix application:
+
+### Standard Integration
+
+In your Remix application, create a `root.tsx` file with proper links to the CSS:
+
+```tsx
+// app/root.tsx
+import type { LinksFunction } from '@remix-run/node';
+
+export const links: LinksFunction = () => [
+  // Option 1: Use the combined CSS file (simplest approach)
+  { rel: 'stylesheet', href: 'npm:baseline-kit/dist/baseline-kit.css' },
+
+  // Option 2: Or use core styles and theme separately
+  // { rel: 'stylesheet', href: 'npm:baseline-kit/dist/styles.css' },
+  // { rel: 'stylesheet', href: 'npm:baseline-kit/dist/theme.css' },
+];
+
+export default function App() {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Links />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+        <LiveReload />
+      </body>
+    </html>
+  );
+}
+```
+
+Note the use of `npm:` prefix which is the recommended way to reference CSS from node_modules in Remix.
+
+### Troubleshooting CSS in Remix
+
+If you're experiencing styling issues with components not showing properly:
+
+1. **Copy to public directory**: For a completely reliable solution, copy the CSS files to your public directory:
+   ```shell
+   mkdir -p public/css
+   cp node_modules/baseline-kit/dist/*.css public/css/
+   ```
+
+   Then reference these local files:
+   ```tsx
+   export const links: LinksFunction = () => [
+     { rel: 'stylesheet', href: '/css/baseline-kit.css' }
+   ];
+   ```
+
+2. **Check CSS specificity**: Make sure your application's CSS isn't overriding Baseline Kit styles. You may need to adjust specificity or load order of your stylesheets.
+
+### Custom Theme Integration
+
+For custom theming:
+
+```tsx
+export const links: LinksFunction = () => [
+  // Core styles (required)
+  { rel: 'stylesheet', href: 'npm:baseline-kit/dist/styles.css' },
+  // Choose one of these theme options:
+  { rel: 'stylesheet', href: 'npm:baseline-kit/dist/theme/default.css' }, // Light theme only
+  { rel: 'stylesheet', href: 'npm:baseline-kit/dist/theme/dark.css' },    // Dark theme only
+  { rel: 'stylesheet', href: '/css/custom-theme.css' },                  // Your custom theme
+];
+```