@tcn/ui-layout

@tcn/ui-layout

A comprehensive layout system that provides flexible, responsive layout components including stacks, grids, tables, and positioning utilities for building modern web applications.

Overview

@tcn/ui-layout provides a complete set of layout primitives that make it easy to create complex, responsive layouts. The package includes stack components for one-dimensional layouts, grid systems for two-dimensional layouts, table components for data display, and utilities for positioning and spacing.

What's Included

Stack Components

• HStack: Horizontal stack for arranging items side-by-side
• VStack: Vertical stack for arranging items in columns
• ZStack: Stack for layering items with z-index control
• Box: Basic container with flexible styling options
• Spacer: Flexible space component for distributing space

Grid System

• Grid: CSS Grid-based layout system with automatic sizing
• Responsive Grid: Grid that adapts to different screen sizes
• Grid Items: Individual grid items with positioning control

Table Components

• Table: Data table with customizable columns and rows
• Column: Column definition with header, cell, and footer rendering
• Cell: Individual table cell with content rendering
• Header: Table header with sticky positioning support

Layout Utilities

• Portal: Render components outside the normal DOM hierarchy
• Popover: Positioned overlay component
• CollapsibleBox: Expandable/collapsible content containers
• Responsive Utilities: Breakpoint-based responsive behavior

Key Features

• Flexbox & Grid: Modern CSS layout techniques for flexible designs
• Responsive Design: Built-in responsive behavior and breakpoint support
• Spacing System: Consistent spacing using design system tokens
• Alignment Control: Precise control over item alignment and distribution
• TypeScript Support: Full type safety with excellent IntelliSense
• Performance Optimized: Efficient rendering with minimal re-renders
• Accessibility: Proper semantic markup and ARIA support

Usage

Basic Stacks

import { HStack, VStack, Spacer } from '@tcn/ui-layout';

function LayoutExample() {
  return (
    <VStack gap="16px" padding="24px">
      <HStack gap="12px" vAlign="center">
        <span>Label:</span>
        <input type="text" />
        <Spacer />
        <button>Submit</button>
      </HStack>

      <VStack gap="8px">
        <div>Item 1</div>
        <div>Item 2</div>
        <div>Item 3</div>
      </VStack>
    </VStack>
  );
}

Grid Layout

import { Grid } from '@tcn/ui-layout';

function GridExample() {
  return (
    <Grid
      itemWidth={200}
      itemHeight={150}
      gap="16px"
      columnAmount={3}
    >
      <div>Grid Item 1</div>
      <div>Grid Item 2</div>
      <div>Grid Item 3</div>
      <div>Grid Item 4</div>
      <div>Grid Item 5</div>
    </Grid>
  );
}

Data Table

import { Table, Column } from '@tcn/ui-layout';

function DataTable() {
  const data = [
    { id: 1, name: 'John Doe', email: '[e-mail]' },
    { id: 2, name: 'Jane Smith', email: '[e-mail]' }
  ];

  return (
    <Table rows={data}>
      <Column
        width={100}
        renderHeader={() => <strong>ID</strong>}
        renderCell={(row) => row.id}
      />
      <Column
        width={200}
        renderHeader={() => <strong>Name</strong>}
        renderCell={(row) => row.name}
      />
      <Column
        width={300}
        renderHeader={() => <strong>Email</strong>}
        renderCell={(row) => row.email}
      />
    </Table>
  );
}

Responsive Layout

import { HStack, VStack } from '@tcn/ui-layout';

function ResponsiveLayout() {
  return (
    <HStack
      gap="24px"
      vAlign="start"
      breakpointPixels={768} // Switch to vertical below 768px
    >
      <VStack gap="16px" width="300px">
        <h3>Sidebar</h3>
        <nav>Navigation items...</nav>
      </VStack>

      <VStack gap="16px" growWeight={1}>
        <h1>Main Content</h1>
        <p>Content goes here...</p>
      </VStack>
    </HStack>
  );
}

Component Features

Stack Components

• Flexible Alignment: Control horizontal and vertical alignment
• Spacing Control: Consistent gaps and padding using design tokens
• Responsive Behavior: Automatic layout switching based on breakpoints
• Size Control: Flexible width, height, and growth/shrink behavior

Grid System

• Automatic Sizing: Items automatically size based on container
• Column Control: Specify exact column amounts or let it auto-fill
• Gap Management: Consistent spacing between grid items
• Responsive Grid: Adapts to different screen sizes

Table System

• Customizable Columns: Define column behavior and rendering
• Sticky Headers: Headers that stick during scrolling
• Row Highlighting: Built-in support for selected rows
• Flexible Cell Rendering: Custom renderers for headers, cells, and footers

Design System Integration

All components automatically integrate with:

• Spacing Scale: Consistent margins, padding, and gaps
• Color System: Primary, secondary, and accent color schemes
• Typography: Font sizes and weights that match your design
• Scalar Support: Automatic scaling for different screen densities
• Theme Support: Light and dark theme compatibility

Responsive Features

• Breakpoint System: Automatic layout switching at defined breakpoints
• Mobile First: Designed with mobile devices in mind
• Flexible Sizing: Components that adapt to container sizes
• Touch Friendly: Optimized for touch interactions

Accessibility Features

• Semantic Markup: Proper HTML structure for screen readers
• ARIA Support: Built-in ARIA attributes and roles
• Keyboard Navigation: Full keyboard support for interactive elements
• Focus Management: Clear focus indicators and focus trapping

When to Use

Choose @tcn/ui-layout when you need:

• Flexible, responsive layouts for your application
• Consistent spacing and alignment across components
• Complex grid-based layouts
• Data tables with custom rendering
• Components that adapt to different screen sizes
• Layout primitives that integrate with your design system

Customization

Components support extensive customization through:

• CSS Custom Properties: Dynamic styling changes
• CSS Modules: Scoped styling with design system integration
• Props Interface: Flexible configuration through component props
• Theme Integration: Automatic adaptation to different themes
• Layout Options: Flexible arrangement and spacing controls

Performance

• Efficient Rendering: Minimal re-renders and optimized updates
• Bundle Optimization: Tree-shakeable components for smaller bundles
• Memory Management: Proper cleanup and event handling
• Lazy Loading: Support for on-demand component loading

License

Apache-2.0