# tinyflow

**Repository Path**: oddity/tinyflow

## Basic Information

- **Project Name**: tinyflow
- **Description**: 一个从零设计的 2D 布局引擎。纯几何计算，不做渲染。没有 Web CSS 的历史包袱。
- **Primary Language**: C
- **License**: BSD-2-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tinyflow

A from-scratch 2D layout engine. Pure geometry, no rendering. No Web CSS legacy baggage.

- **Pure C ABI** header + C++ implementation, compiles to static library
- **Opaque handles** — zero internal leakage in public header
- **User allocator** — all memory through your callbacks
- **Two orthogonal systems** — Flow layout (elements push each other) + Attach anchor layer (elements float above)
- **Dirty incremental** — only recompute what changed
- **Stress tested** — 2000+ children in one container, 500+ levels deep nesting

## Quick Start

```cmake
add_library(tinyflow STATIC src/tinyflow.cc)
target_compile_definitions(tinyflow PUBLIC TINYFLOW_STATIC=1)
target_include_directories(tinyflow PUBLIC src/)
```

```c
#include "tinyflow.h"

tinyflow_allocator_callbacks alloc = { malloc, free };
tinyflow_set_allocator(&alloc);

tinyflow_node* root = tinyflow_node_create();
// ... set styles, add children ...

tinyflow_compute(root, &constraint, &ctx);
tinyflow_compute_attaches(root, &ctx);
```

## Build

### xmake (recommended)

```bash
# Build library only
xmake

# Build with tests and examples
xmake f --tests=y --examples=y
xmake

# Run tests
xmake run test_basic

# Run example
xmake run exam_basic
```

### CMake

```bash
# Configure
cmake -S . -B build-cmake -G "Visual Studio 17 2022" -A x64

# Build
cmake --build build-cmake --config Release

# Run tests
ctest --test-dir build-cmake -C Release --output-on-failure

# Build examples (optional)
cmake -S . -B build-cmake -DTINYFLOW_BUILD_EXAMPLES=ON
cmake --build build-cmake --config Release
```

## Documentation

Full documentation (design philosophy, core model, usage guide, API reference, integration guide, FAQ):

**[docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)**

## Examples

- **[examples/basic/main.c](examples/basic/main.c)** — minimal workflow: flex row with fixed sidebar + flexible main

## Project Structure

```
tinyflow/
├── xmake.lua            # xmake build config (root)
├── CMakeLists.txt       # CMake build config
├── README.md            # This file
├── LICENSE              # MIT
├── docs/
│   └── DOCUMENTATION.md # Full documentation (10 chapters)
├── examples/
│   ├── xmake.lua        # xmake config for examples
│   └── basic/
│       └── main.c       # Minimal usage example
├── src/
│   ├── xmake.lua        # xmake config for library
│   ├── tinyflow.h       # Pure C ABI header
│   └── tinyflow.cc      # C++ implementation
└── tests/
    ├── xmake.lua        # xmake config for tests
    └── basic/
        └── main.cc      # 22 test groups, 209 assertions
```

## Design Principles

1. **One model, not a stack of models** — Flow + Attach, two orthogonal systems
2. **Explicit over implicit** — no BFC, no containing block inference, no hidden formatting contexts
3. **Safe defaults** — flexShrink defaults to 0, no margin collapse, percentages reference corresponding axis
4. **Pure geometry** — layout engine only computes positions, rendering layer handles clipping/scrolling/z-order
5. **Embeddable, non-intrusive** — pure C ABI, opaque handles, user allocator

## Version

1.0.0 — see [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) for details.