@senka-ai/layout-engine

Intuitive layout system for Senka's no-code platform that enables non-technical users to create professional, responsive layouts through visual tools.

Features

• 🎯 Intuitive Arrangements: Think in spatial terms (Stack, Row, Grid) not CSS
• 📐 Smart Constraints: Flexible positioning with automatic conflict resolution
• 📱 Responsive by Default: Automatic mobile optimization with override capability
• 🎨 Visual Controls: Drag-and-drop with real-time preview
• 🔒 Modification Safety: Preview changes before applying with rollback
• ⚡ Performance Optimized: Minimal CSS output with intelligent caching

Installation

npm install @senka-ai/layout-engine

Basic Usage

import { LayoutEngine } from '@senka-ai/layout-engine'

const engine = new LayoutEngine()

// Create a simple stack layout - no 'as const' needed!
const layout = {
  id: 'main-layout',
  type: 'stack',
  direction: 'vertical',
  gap: 'normal',
  fillContainer: true,
  responsive: {
    automatic: {
      enabled: true,
      mobileOptimization: 'balanced',
    },
  },
}

// Generate CSS
const css = engine.generateCSS(layout)

Arrangement Types

Stack

Elements arranged vertically (or horizontally), one after another.

{
  id: 'my-stack',
  type: 'stack',
  direction: 'vertical', // or 'horizontal'
  reverse: false,
  gap: 'normal'
}

Row

Elements arranged side-by-side horizontally.

{
  id: 'my-row',
  type: 'row',
  wrap: true,
  reverse: false,
  gap: 'normal',
  align: 'center'
}

Grid

Elements arranged in a structured grid pattern.

{
  id: 'my-grid',
  type: 'grid',
  columns: 3,
  gap: 'normal',
  fillContainer: true
}

Flow

Elements flow naturally like text, wrapping when needed.

{
  id: 'my-flow',
  type: 'flow',
  gap: 'cozy',
  align: 'start'
}

Overlay

Elements layered on top of each other.

{
  id: 'my-overlay',
  type: 'overlay',
  position: 'center',
  zIndex: 10
}

Spacing System

Use semantic spacing values, direct numbers, or spacing objects:

// Semantic spacing (recommended)
{
  gap: 'tight',        // 4px
  padding: 'cozy',     // 8px
}

// Direct numbers
{
  gap: 16,             // 16px
  padding: 24,         // 24px
}

// Spacing objects for custom values
{
  gap: { scale: 'custom', custom: 20 },
  padding: {
    top: { scale: 'normal' },    // 16px
    horizontal: { scale: 'cozy' } // 8px
  }
}

Available scales: 'tight' (4px), 'cozy' (8px), 'normal' (16px), 'comfortable' (24px), 'spacious' (32px)

Responsive Features

Automatic Optimization

{
  responsive: {
    automatic: {
      enabled: true,
      mobileOptimization: 'aggressive',
      rules: {
        stackRowsOnMobile: true,
        increaseSpacingForTouch: true,
        simplifyGridsOnMobile: true
      }
    }
  }
}

Custom Breakpoints

{
  responsive: {
    breakpointRules: {
      mobile: {
        arrangement: { type: 'stack' },
        spacing: { gap: 'comfortable' }
      },
      desktop: {
        arrangement: { type: 'row' },
        spacing: { gap: 'normal' }
      }
    }
  }
}

Constraints

Pin elements to edges or center them:

{
  constraints: {
    horizontal: {
      left: { enabled: true, offset: 20 },
      right: { enabled: true, offset: 20 }
    },
    vertical: {
      centerV: true
    }
  }
}

Visual Controls (Svelte Components)

<script>
  import { ArrangementPicker, SpacingSlider } from '@senka-ai/layout-engine'

  let arrangement = 'stack'
  let spacing = 'normal'
</script>

<ArrangementPicker bind:value={arrangement} />
<SpacingSlider bind:value={spacing} />

API Reference

LayoutEngine

Main class for generating CSS from layout definitions.

const engine = new LayoutEngine(options?: LayoutEngineOptions)

// Generate CSS
engine.generateCSS(layout: LayoutContainer): string

// Optimize for platform
engine.optimizeForPlatform(layout: LayoutContainer, platform: Platform): LayoutContainer

// Validate layout
engine.validate(layout: LayoutContainer): ValidationResult

Types

See TypeScript definitions for complete type information.

License

MIT