# @tachui/primitives

Foundation UI components for tachUI applications - the building blocks of modern web interfaces.

## Overview

The `@tachui/primitives` package provides essential UI components that serve as the foundation for all tachUI applications. These components offer SwiftUI-inspired APIs with web-native performance and accessibility.

## Installation

```bash
npm install @tachui/primitives
# or
pnpm add @tachui/primitives
```

## Core Components

### Layout Components

#### VStack

Vertically stacks child components with customizable spacing and alignment.

```typescript
import { VStack, Text } from '@tachui/primitives'

VStack({
  spacing: 16,
  alignment: 'leading',
  children: [Text('First Item'), Text('Second Item'), Text('Third Item')],
})
```

#### HStack

Horizontally arranges child components with flexible alignment options.

```typescript
import { HStack, Button } from '@tachui/primitives'

HStack({
  spacing: 12,
  alignment: 'center',
  children: [Button('Cancel'), Spacer(), Button('Save')],
})
```

#### ZStack

Overlays components on top of each other with alignment control.

```typescript
import { ZStack, Image, Text } from '@tachui/primitives'

ZStack({
  alignment: 'bottomTrailing',
  children: [
    Image('/hero-background.jpg'),
    Text('Overlay Text')
      .padding(16)
      .backgroundColor('rgba(0,0,0,0.7)')
      .foregroundColor('white')
      ,
  ],
})
```

#### Spacer

Flexible space that expands to fill available space in stacks.

```typescript
HStack({
  children: [
    Text('Left'),
    Spacer(), // Pushes content to edges
    Text('Right'),
  ],
})
```

#### Divider

Visual separator line with customizable appearance.

```typescript
VStack({
  children: [Text('Section 1'), Divider(), Text('Section 2')],
})
```

### Shapes

`Circle`, `Rectangle`, `RoundedRectangle`, `Ellipse` and `Capsule` fill their
frame and are styled with `.fill()`, `.stroke()`, `.strokeBorder()`,
`.inset()`, `.trim()` and `.strokeStyle()`, which chain with modifiers in
either order.

| Shape | Geometry |
| --- | --- |
| `Circle()` | Inscribed in the short side of its frame, centered |
| `Rectangle()` | The frame itself, square corners |
| `RoundedRectangle(cornerRadius)` | Circular corners, clamped to half the short side |
| `Ellipse()` | Fills the frame, one radius per axis |
| `Capsule()` | Semicircular caps on the short axis, either orientation |

```typescript
Circle().fill('#007AFF').frame({ width: 12, height: 12 })

RoundedRectangle(12).strokeBorder('#E5E5EA', 1)
RoundedRectangle({ cornerRadius: 12 }).fill('#F2F2F7')
Capsule().fill('#007AFF').frame({ width: 64, height: 24 })

Image(source)
  .frame({ width: 40, height: 40 })
  .clipShape('circle')
  .overlay(Circle().inset(1).stroke('#007AFF', 2)) // a ring 1px inside the edge
```

`.trim(from, to)` draws part of the path, for progress rings and spinners:

```typescript
Circle()
  .trim(0, progress)
  .strokeStyle({ lineWidth: 4, lineCap: 'round' })
  .stroke('#007AFF')
  .transform('rotate(-90deg)') // the path starts at three o'clock, as in SwiftUI
```

`.trim()` strokes; it does not shorten the path. SVG ignores a dash pattern
when filling, so a trimmed shape still fills — and clips — as the whole shape.

Trim and `strokeStyle`'s `dash` are exclusive — both use `stroke-dasharray`,
so a shape carrying both draws the trim and warns once.

`RoundedRectangle`'s radius is clamped to half the short side, as in SwiftUI, so
an over-large radius draws a capsule instead of distorting into elliptical
corners.

`.inset()` and `.strokeBorder()` leave that radius alone, so subtract from it
yourself where you want corners concentric with the host:
`RoundedRectangle(12).strokeBorder(tint, 4)` has an outer stroke edge of radius
14, two pixels proud of a `cornerRadius: 12` host, while
`RoundedRectangle(10).strokeBorder(tint, 4)` lands flush. `Capsule` and `Circle`
recompute their curvature from the inset rect and need no such help. `Ellipse`
stays inside its frame but is not flush with an elliptical host: the parallel
curve of an ellipse is not an ellipse, so the border bulges between the axis
extremes.

### Display Components

#### Text

Displays text content with full typography control.

```typescript
Text('Hello, tachUI!')
  .font({ family: 'San Francisco', size: 18, weight: 600 })
  .foregroundColor('#007AFF')
  .textAlign('center')
  
```

**Advanced Text Features:**

```typescript
// Multiline text with line clamping
Text(longContent).lineClamp(3).wordBreak('break-word')

// Reactive text content
const [count, setCount] = createSignal(0)
Text(() => `Count: ${count()}`)
```

#### Image

Displays images with loading states and aspect ratio control.

```typescript
Image('/path/to/image.jpg')
  .size({ width: 200, height: 150 })
  .cornerRadius(8)
  .aspectRatio('cover')
  
```

**Image with Assets:**

```typescript
import { Assets } from '@tachui/core'

Image(Assets.profilePicture)
  .size({ width: 60, height: 60 })
  .cornerRadius(30)
  
```

#### HTML

Renders raw HTML content safely with sanitization.

```typescript
HTML({
  content: '<p>Safe <strong>HTML</strong> content</p>',
  sanitize: true,
})
```

### Control Components

#### Button

Interactive button component with full customization support.

```typescript
Button('Click Me', () => {
  console.log('Button clicked!')
})
  .padding({ horizontal: 16, vertical: 8 })
  .backgroundColor('#007AFF')
  .foregroundColor('white')
  .cornerRadius(8)
  
```

**Button States:**

```typescript
Button('Stateful Button', handleClick)
  .backgroundColor('#007AFF')
  .hover({ backgroundColor: '#0051D5' })
  .active({ transform: 'scale(0.95)' })
  .disabled({ opacity: 0.5 })
  
```

#### Toggle

Switch/toggle component for boolean states.

```typescript
const [isEnabled, setIsEnabled] = createSignal(false)

Toggle({
  isOn: () => isEnabled(),
  onToggle: setIsEnabled,
})
  .accentColor('#007AFF')
  
```

#### Picker

Selection component for choosing from multiple options.

```typescript
const options = ['Option 1', 'Option 2', 'Option 3']
const [selected, setSelected] = createSignal(options[0])

Picker({
  selection: () => selected(),
  onSelectionChange: setSelected,
  options: options,
  renderOption: option => Text(option),
})
```

### Form Components

#### BasicInput

Text input component with validation and formatting support.

```typescript
const [text, setText] = createSignal('')

BasicInput({
  value: () => text(),
  onInput: setText,
  placeholder: 'Enter your name',
})
  .padding(12)
  .border(1, '#E5E5EA')
  .cornerRadius(8)
  
```

**Advanced Input Features:**

```typescript
BasicInput({
  value: () => email(),
  onInput: setEmail,
  type: 'email',
  validation: value => value.includes('@'),
  errorMessage: 'Please enter a valid email',
})
```

#### BasicForm

Simple form container with validation and submission handling.

```typescript
BasicForm({
  onSubmit: data => {
    console.log('Form submitted:', data)
  },
  children: [
    BasicInput({ name: 'username', placeholder: 'Username' }),
    BasicInput({ name: 'email', type: 'email', placeholder: 'Email' }),
    Button('Submit', null), // null indicates form submission
  ],
})
```

## Usage Patterns

### Building Complex Layouts

```typescript
VStack({
  spacing: 20,
  children: [
    // Header
    HStack({
      alignment: 'center',
      children: [
        Image(Assets.logo).size({ width: 40, height: 40 }),
        Text('My App').font({ size: 24, weight: 'bold' }),
        Spacer(),
        Button('Menu', toggleMenu),
      ],
    }),

    // Content
    VStack({
      spacing: 16,
      children: [
        Text('Welcome to tachUI!')
          .font({ size: 18 })
          .textAlign('center')
          ,

        Divider(),

        HStack({
          spacing: 12,
          children: [
            Button('Get Started', startOnboarding),
            Button('Learn More', openDocs)
              .backgroundColor('transparent')
              .foregroundColor('#007AFF')
              ,
          ],
        }),
      ],
    }),
  ],
})
```

### Responsive Design

```typescript
VStack({
  children: items.map(item =>
    HStack({
      spacing: { mobile: 8, desktop: 16 },
      children: [
        Image(item.image)
          .size({ mobile: 40, desktop: 60 })
          .cornerRadius({ mobile: 4, desktop: 8 })
          ,

        VStack({
          alignment: 'leading',
          children: [
            Text(item.title)
              .font({ size: { mobile: 16, desktop: 18 } })
              ,

            Text(item.description)
              .font({ size: { mobile: 14, desktop: 16 } })
              .opacity(0.7)
              ,
          ],
        }),
      ],
    })
  ),
})
```

## Accessibility Features

All primitive components include comprehensive accessibility support:

- **ARIA Labels**: Automatic and customizable ARIA attributes
- **Keyboard Navigation**: Full keyboard support for interactive elements
- **Screen Reader Support**: Optimized for screen reader compatibility
- **Focus Management**: Proper focus handling and visual indicators
- **High Contrast**: Support for high contrast modes

```typescript
Button('Accessible Button', handleClick)
  .accessibilityLabel('Save document')
  .accessibilityRole('button')
  .accessibilityHint('Saves the current document')
  
```

## Styling Integration

Primitives work seamlessly with the modifier system:

```typescript
import { padding, margin, backgroundColor } from '@tachui/modifiers'

Text('Styled with modifiers')
  .apply(padding(16))
  .apply(margin({ vertical: 8 }))
  .apply(backgroundColor('#F2F2F7'))
  
```

## Performance Characteristics

- **Minimal Bundle Size**: Tree-shakeable components
- **Efficient Rendering**: Fine-grained reactivity with minimal re-renders
- **Memory Efficient**: Automatic cleanup and memory management
- **GPU Accelerated**: CSS transforms and animations when possible

## Component Validation

Built-in validation ensures proper component usage:

```typescript
// Development warnings for common mistakes
VStack({
  children: 'String', // ❌ Warning: children should be array
})

// Type-safe props
Text(123) // ❌ TypeScript error: content must be string or signal
```

## Integration with Other Packages

### With Flow Control

```typescript
import { Show, ForEach } from '@tachui/flow-control'

VStack({
  children: [
    Show({
      when: () => isLoading(),
      children: Text('Loading...'),
    }),

    ForEach({
      data: () => items(),
      renderItem: item =>
        HStack({
          children: [
            Text(item.name),
            Spacer(),
            Button('Edit', () => editItem(item)),
          ],
        }),
    }),
  ],
})
```

### With Navigation

```typescript
import { NavigationLink } from '@tachui/navigation'

VStack({
  children: [
    NavigationLink({
      destination: '/profile',
      children: HStack({
        children: [
          Image(userAvatar),
          Text(userName),
          Spacer(),
          Text('>').opacity(0.5),
        ],
      }),
    }),
  ],
})
```

## Best Practices

1. **Use Semantic Components**: Choose components based on meaning, not appearance
2. **Leverage the Stack System**: Use VStack, HStack, and ZStack for layouts instead of CSS
3. **Apply Modifiers Consistently**: Use the modifier chain for all styling
4. **Consider Accessibility**: Always provide appropriate labels and roles
5. **Optimize for Performance**: Use signals for reactive content, avoid object creation in renders

## Browser Support

- Modern browsers (Chrome 88+, Firefox 85+, Safari 14+, Edge 88+)
- Progressive enhancement for older browsers
- Graceful fallback for unsupported features

## License

This package is part of the tachUI framework and is licensed under the MPL-2.0 License.