npm - @rhavenside/baseline - Versions diffs - 2.0.7 → 2.1.0 - Mend

@rhavenside/baseline 2.0.7 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -9,6 +9,12 @@ A strict, layer-based design system with semantic tokens. Features a custom nami
 [![npm version](https://img.shields.io/npm/v/@rhavenside/baseline.svg)](https://www.npmjs.com/package/@rhavenside/baseline)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<div align="center">
+**[📚 Documentation](https://baseline.rhavenside.de)** • **[🎨 Examples](https://examples.rhavenside.de)**
+</div>
 ## Installation
 Install Base-Line via npm:
@@ -25,6 +31,8 @@ Or via CDN:
 ## Quick Start
+Base-Line automatically includes [Cadence](https://www.npmjs.com/package/@rhavenside/cadence) for motion and [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold) for layouts. No additional setup required!
 ### CSS Only
 Include the CSS file in your HTML:
@@ -39,8 +47,8 @@ Include the CSS file in your HTML:
   <title>Base-Line Example</title>
 </head>
 <body>
-  <div class="l-container">
-    <div class="l-stack l-stack--lg">
+  <div class="scaffold-container">
+    <div class="scaffold-stack scaffold-stack--spacing-lg">
       <h1>Hello Base-Line</h1>
       <p>Welcome to the Base-Line Design System</p>
       <button class="c-button c-button--primary">Get Started</button>
@@ -50,6 +58,8 @@ Include the CSS file in your HTML:
 </html>
 ```
+**Note:** The example above uses Scaffold layout classes (`scaffold-container`, `scaffold-stack`) for structured layouts. All components use Cadence motion mixins automatically for smooth, consistent animations.
 ### With JavaScript
 For interactive components (modals, dropdowns, tooltips, etc.), include the JavaScript:
@@ -119,7 +129,7 @@ All design values are defined via CSS Custom Properties:
 - **Colors**: Surface, Text, Accent, Border, State colors
 - **Typography**: Font families, sizes, line-height, weight
-- **Spacing**: Consistent step scale (4px base)
+- **Spacing**: Consistent step scale (based on Scaffold spacing: 8px/0.5rem base)
 - **Radius**: Border-radius values
 - **Shadow**: Shadow definitions
 - **Z-Index**: Z-index scale
@@ -129,15 +139,114 @@ All design values are defined via CSS Custom Properties:
 ### Layer 2: Layout System
-Layout classes for standard layouts without custom CSS:
+Layout classes for standard layouts without custom CSS (powered by [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold)):
-- `l-container` - Container with max-width + responsive padding
-- `l-stack` - Vertical layouts
-- `l-cluster` - Horizontal groups
-- `l-grid` - Flexible grid layouts (auto-fit / auto-fill)
+- `scaffold-container` - Container with max-width + responsive padding
+- `scaffold-stack` - Vertical layouts with spacing options
+- `scaffold-grid` - Flexible grid layouts (responsive columns)
+- `scaffold-padding-*` - Padding utilities (xs, sm, md, lg, xl, xxl) with directional variants
+- `scaffold-margin-*` - Margin utilities (xs, sm, md, lg, xl, xxl) with directional variants
 **Rule:** No colors, no typography in layout classes.
+**Example:**
+```html
+<div class="scaffold-container">
+  <div class="scaffold-stack scaffold-stack--spacing-lg">
+    <h1>Title</h1>
+    <p>Content</p>
+  </div>
+  <div class="scaffold-grid scaffold-grid--cols-3">
+    <div class="c-card">Card 1</div>
+    <div class="c-card">Card 2</div>
+    <div class="c-card">Card 3</div>
+  </div>
+</div>
+```
+### Motion System (Cadence)
+All animations and transitions use [Cadence](https://www.npmjs.com/package/@rhavenside/cadence) for consistent motion timing:
+- **motion-response()** - For direct user interactions (150ms) - Used in buttons, inputs, form controls
+- **motion-transition()** - For state changes (300ms) - Used in modals, dropdowns, tooltips, alerts
+- **motion-ambient()** - For continuous animations (varies) - Used in spinners, progress bars
+- **motion-instant()** - For immediate changes (0ms) - Used for instant state updates
+All components automatically use the appropriate motion intention based on their interaction pattern. This ensures consistent, accessible animations throughout your application.
+## How Cadence, Scaffold, and Baseline Work Together
+Base-Line is built on three complementary systems that work seamlessly together:
+### Baseline - The Design System
+**Baseline** provides the core design system:
+- **Components**: Buttons, Cards, Modals, Forms, and 20+ other UI components
+- **Design Tokens**: Colors, typography, spacing, shadows, and other design values
+- **Utilities**: Limited utility classes for common needs
+### Scaffold - The Layout System
+**Scaffold** provides structured layout classes:
+- **Container**: `scaffold-container` for max-width containers with responsive padding
+- **Stack**: `scaffold-stack` for vertical layouts with consistent spacing
+- **Grid**: `scaffold-grid` for flexible, responsive grid layouts
+- **Padding**: Responsive padding utilities
+Scaffold handles the **structure** of your page - where things are positioned and how they're spaced.
+> **Note:** Scaffold can also be used independently. See [@rhavenside/scaffold](https://www.npmjs.com/package/@rhavenside/scaffold) for standalone usage.
+### Cadence - The Motion System
+**Cadence** provides consistent motion and animations:
+- **Motion Intentions**: Different timing for different interaction types
+  - `motion-response()` - Fast feedback for direct user actions (150ms)
+  - `motion-transition()` - Smooth state changes (300ms)
+  - `motion-ambient()` - Continuous animations (varies)
+- **Automatic Integration**: All Baseline components automatically use Cadence for animations
+Cadence handles the **motion** - how things animate and transition.
+> **Note:** Cadence can also be used independently. See [@rhavenside/cadence](https://www.npmjs.com/package/@rhavenside/cadence) for standalone usage.
+### Working Together
+Here's how they work together in practice:
+```html
+<!-- Scaffold provides the layout structure -->
+<div class="scaffold-container">
+  <div class="scaffold-stack scaffold-stack--spacing-lg">
+    <!-- Baseline provides the components -->
+    <h1>Welcome</h1>
+    <button class="c-button c-button--primary">Get Started</button>
+    <!-- Cadence automatically animates the button on hover/click -->
+    <!-- Scaffold provides spacing between elements -->
+    <div class="scaffold-grid scaffold-grid--cols-3">
+      <div class="c-card">
+        <!-- Cadence animates card hover states -->
+        Card 1
+      </div>
+      <div class="c-card">Card 2</div>
+      <div class="c-card">Card 3</div>
+    </div>
+  </div>
+</div>
+```
+**In summary:**
+- **Scaffold** = Where things go (layout structure)
+- **Baseline** = What things look like (components and design)
+- **Cadence** = How things move (animations and transitions)
+All three are included automatically when you install `@rhavenside/baseline` - no additional setup required!
+> **Note:** This is a high-level overview. Detailed documentation for each system is available in the [full documentation](https://baseline.rhavenside.de).
 ### Layer 3: Components
 Fully functional components with JavaScript support:
@@ -198,13 +307,14 @@ Format: `--<category>-<meaning>[-<level>]`
 ### Layout Classes
-Format: `l-<role>`
+Format: `scaffold-<role>` (powered by [Scaffold](https://www.npmjs.com/package/@rhavenside/scaffold))
 ```html
-<div class="l-container">
-<div class="l-stack l-stack--lg">
-<div class="l-cluster l-cluster--center">
-<div class="l-grid l-grid--auto-fit">
+<div class="scaffold-container">
+<div class="scaffold-stack scaffold-stack--spacing-lg">
+<div class="scaffold-stack scaffold-stack--horizontal scaffold-stack--align-center">
+<div class="scaffold-grid scaffold-grid--cols-3">
+<div class="scaffold-padding-sm scaffold-margin-top-md">
 ```
 ### Components
@@ -222,7 +332,7 @@ Format: `c-<component>`
 - `c-alert--danger`, `c-alert--success`
 **Global States:**
-- `is-hovered`, `is-active`, `is-disabled`
+- `is-active`, `is-disabled`, `is-show` (for collapse/accordion)
 - `is-loading`, `is-open`, `has-error`
 ### Utilities
@@ -394,19 +504,68 @@ const tooltip = window.BaseLine.Tooltip.getOrCreateInstance(element)
 ### Form
 ```html
-<div class="l-stack l-stack--sm">
-  <label class="c-form-label" for="email">Email</label>
-  <input type="email" class="c-form-control" id="email" placeholder="name@example.com">
-</div>
+<div class="scaffold-container scaffold-container--narrow">
+  <div class="scaffold-stack scaffold-stack--spacing-md">
+    <div class="scaffold-stack scaffold-stack--spacing-sm">
+      <label class="c-form-label" for="email">Email</label>
+      <input type="email" class="c-form-control" id="email" placeholder="name@example.com">
+    </div>
+    <div class="scaffold-stack scaffold-stack--spacing-sm">
+      <label class="c-form-label" for="password">Password</label>
+      <input type="password" class="c-form-control" id="password">
+    </div>
-<div class="l-stack l-stack--sm">
-  <label class="c-form-label" for="password">Password</label>
-  <input type="password" class="c-form-control" id="password">
+    <button type="submit" class="c-button c-button--primary">Submit</button>
+  </div>
 </div>
+```
+**Note:** This example demonstrates Scaffold layout classes for structured form layouts. All form inputs automatically use Cadence motion-response() for smooth focus and interaction transitions.
+### Accordion
-<button type="submit" class="c-button c-button--primary">Submit</button>
+```html
+<div class="c-accordion" id="accordionExample">
+  <div class="c-accordion-item">
+    <h2 class="c-accordion-header">
+      <button
+        class="c-accordion-button"
+        type="button"
+        data-c-toggle="collapse"
+        data-c-target="#collapseOne"
+        data-c-parent="#accordionExample">
+        Accordion Item #1
+      </button>
+    </h2>
+    <div id="collapseOne" class="c-collapse is-show" data-c-parent="#accordionExample">
+      <div class="c-accordion-body">
+        This is the first accordion body. It is open by default (has `is-show` class).
+      </div>
+    </div>
+  </div>
+  <div class="c-accordion-item">
+    <h2 class="c-accordion-header">
+      <button
+        class="c-accordion-button c-collapsed"
+        type="button"
+        data-c-toggle="collapse"
+        data-c-target="#collapseTwo"
+        data-c-parent="#accordionExample">
+        Accordion Item #2
+      </button>
+    </h2>
+    <div id="collapseTwo" class="c-collapse" data-c-parent="#accordionExample">
+      <div class="c-accordion-body">
+        This is the second accordion body. It is closed by default (no `is-show` class, button has `c-collapsed`).
+      </div>
+    </div>
+  </div>
+</div>
 ```
+**Note:** By default, only the first accordion item should be open (with `is-show` class on the collapse element). Other items should be closed (no `is-show` class, button has `c-collapsed` class). Accordions use Cadence motion-transition() for smooth expand/collapse animations.
 ## Dark Mode
 Dark mode is automatically activated via `prefers-color-scheme`. Additionally, the `.theme-dark` class can be set manually:
@@ -455,7 +614,72 @@ Base-Line supports all modern browsers:
 ## Dependencies
-- **@popperjs/core**: ^2.11.8 (for positioning tooltips, popovers, dropdowns)
+Base-Line includes the following peer dependencies that are automatically installed:
+- **@rhavenside/cadence**: ^1.0.1 - Motion system for consistent animations and transitions
+- **@rhavenside/scaffold**: ^1.1.7 - Layout system for structured page layouts
+- **@popperjs/core**: ^2.11.8 - For positioning tooltips, popovers, and dropdowns
+All dependencies are automatically installed when you install `@rhavenside/baseline`. No additional setup required!
+## Version History
+### Version 2.1.0 and above
+**New Dependencies: Scaffold and Cadence Integration**
+Version 2.1.0 introduces two new integrated systems:
+**Scaffold Layout System (NEW)**
+- **Scaffold is now included**: Scaffold layout classes are now part of Base-Line
+- **Layout Classes Available**: Use `scaffold-container`, `scaffold-stack`, `scaffold-grid` for structured page layouts
+- **Responsive by Default**: All Scaffold classes are responsive and work seamlessly with Baseline components
+**Cadence Motion System Integration**
+All interactive components now use the Cadence motion system for consistent, accessible animations:
+- **Motion-Mixins in Components**: 10 components have been updated to use Cadence motion mixins:
+  - `motion-transition()` for state changes (Alert, Toast, Tooltip, Popover, Dropdown, Accordion, Floating Label)
+  - `motion-response()` for direct user interactions (Form Range, List Group)
+- **Consistent Animation Timing**: All components now follow the same motion principles:
+  - 150ms for direct user interactions (`motion-response`)
+  - 300ms for state changes (`motion-transition`)
+- **Improved Documentation**: README now includes comprehensive documentation for:
+  - Cadence motion system integration
+  - Scaffold layout system usage
+  - Dependencies and their purposes
+**Benefits:**
+- Structured layout system (Scaffold) for consistent page layouts
+- More consistent animations across all components (Cadence)
+- Better accessibility (respects `prefers-reduced-motion`)
+- Easier to maintain and extend motion behavior
+- Clear motion intentions for different interaction types
+### Version 2.0.8 and below
+**Before 2.1.0:**
+- **No Scaffold**: Layout classes were not available - developers had to create their own layout solutions
+- **No unified motion system**: Components used hardcoded transition values or CSS variables for animations
+- **Manual transition timing**: Manual transition timing management required
+- **Less consistent**: Less consistent animation behavior across components
+**Migration Notes:**
+If you're upgrading from 2.0.8 or earlier:
+- **No breaking changes**: All existing code will continue to work without modifications
+- **Scaffold is NEW**: Scaffold layout classes (`scaffold-container`, `scaffold-stack`, `scaffold-grid`, etc.) are now available in Base-Line 2.1.0. You can start using them for structured page layouts
+- **Motion improvements are internal**: The Cadence motion mixins are internal improvements that make animations more consistent. Existing component behavior remains the same
+- **New features available**: You can now take advantage of:
+  - Scaffold layout system for structured page layouts
+  - More consistent animations (automatic, no code changes needed)
+  - Better motion system documentation
+If you were using custom transitions that override component defaults, you may want to review them to ensure they align with the new motion system principles (150ms for interactions, 300ms for state changes).
 ## License