swiftbricks/README.md

# SwiftBricks

Bricks JSON-based UI框架的 Swift/SwiftUI 原生实现。

支持 macOS 14+、iOS 17+、iPadOS 17+。

## 核心思想

与Bricks一致：**JSON驱动、声明式、无代码**。
UI从JSON schema渲染，交互通过binds声明，无需手写SwiftUI视图代码。

## 架构

```
SwiftBricks/
├── Core/
│   ├── Schema.swift      — JSON schema Codable模型
│   ├── Store.swift       — 数据存储（widget值/表单/表格/弹窗状态）
│   ├── EventBus.swift    — 事件发布/订阅
│   ├── RPC.swift         — 网络层（GET/POST/Form/认证）
│   ├── Engine.swift      — 核心引擎（加载/索引/binds/验证/提交）
│   └── I18n.swift        — 国际化（多语言JSON文件）
├── Controls/
│   ├── TextControl.swift — Text, Title1-6, Label
│   ├── InputControl.swift — Input, Textarea, Number, Date
│   ├── ButtonControl.swift — Button, Select
│   ├── VBoxControl.swift — VBox, HBox, ScrollPanel, DynamicColumn
│   ├── TabularControl.swift — Tabular/DataViewer（表格）
│   ├── FormControl.swift — Form, InlineForm（表单+验证）
│   └── TabViewControl.swift — TabView, Menu, PopupWindow, Html, Image, UrlWidget
├── Renderer/
│   ├── BricksView.swift  — 主入口视图（JSON→渲染+弹窗层+错误处理）
│   └── ControlRenderer.swift — 递归widget分发渲染器
└── SwiftBricks.swift     — 公开API + 类型别名
```

## 支持的Widget类型（30+）

| 类别 | Widget |
|------|--------|
| 文本 | Text, Title1-6, Label |
| 输入 | Input, Textarea, UiStr, UiNumber, UiDate, UiText, UiCode, Select |
| 按钮 | Button |
| 布局 | VBox, HBox, VScrollPanel, HScrollPanel, Filler, DynamicColumn, Card |
| 数据 | Tabular, DataViewer, Form, InlineForm |
| 导航 | TabView, Menu |
| 弹窗 | PopupWindow |
| 其他 | Html, Image, urlwidget |

## 支持的Bind ActionType（9种）

`newwindow` `iframe` `urlwidget` `urldata` `bricks` `registerfunction` `method` `script` `event`

## 用法

### 基本使用

```swift
import SwiftBricks

// 1. 创建引擎
let engine = BricksEngine()
engine.rpc.baseURL = "https://your-api.com"
engine.rpc.authToken = "your-token"

// 2. 渲染JSON
BricksView(json: """
{
    "widgettype": "VBox",
    "options": { "css": "card", "padding": "16px" },
    "subwidgets": [
        { "widgettype": "Title2", "options": { "text": "Hello" } },
        { "widgettype": "Button", "options": { "label": "Click Me" },
          "binds": [{"wid": "self", "event": "click", "actiontype": "event",
                     "target": "say_hello"}] }
    ]
}
""", engine: engine)
```

### 从远程URL加载

```swift
BricksView(url: "/api/page.ui", engine: engine)
```

### 国际化

```swift
// 加载语言文件: {basePath}/i18n/en/i18n.json
engine.i18n.basePath = "https://your-cdn.com"
await engine.i18n.loadLocale("en")

// JSON中 i18n 属性控制是否翻译
{ "widgettype": "Text", "options": { "text": "你好", "i18n": true } }
```

### 表单验证

```json
{
    "widgettype": "Form",
    "options": {
        "submit_url": "/api/submit.dspy",
        "fields": [
            { "name": "email", "label": "邮箱", "uitype": "str", "required": true,
              "rules": [
                { "type": "required", "message": "邮箱必填" },
                { "type": "email", "message": "格式不正确" }
              ] }
        ]
    }
}
```

### 表格（Tabular）

```json
{
    "widgettype": "Tabular",
    "options": {
        "data_url": "/api/list.dspy",
        "page_rows": 20,
        "row_options": {
            "fields": [
                { "name": "id", "label": "ID", "uitype": "str" },
                { "name": "name", "label": "名称", "cwidth": 12, "uitype": "str" }
            ],
            "browserfields": {
                "exclouded": ["id"]
            }
        }
    }
}
```

### 侧边栏菜单

```json
{
    "widgettype": "Menu",
    "options": {
        "items": [
            { "name": "home", "label": "首页", "icon": "🏠",
              "binds": [{"wid":"self","event":"click","actiontype":"urlwidget",
                         "target":"content","options":{"url":"/home.ui"}}] },
            { "name": "settings", "label": "设置", "icon": "⚙️",
              "submenu": [
                { "name": "profile", "label": "个人信息" },
                { "name": "security", "label": "安全" }
              ] }
        ]
    }
}
```

## 与Bricks Web版的差异

| 特性 | Bricks (Web) | SwiftBricks |
|------|-------------|-------------|
| 渲染 | DOM | SwiftUI |
| 状态 | widget实例属性 | ObservableObject Store |
| 事件 | DOM事件+dispatch | EventBus发布/订阅 |
| 网络 | bricks.tget/fetch | BricksRPC (URLSession) |
| 脚本 | actiontype:script可用 | 不支持（遵循无代码哲学） |
| 平台 | 浏览器 | macOS/iOS/iPadOS |

## 构建

```bash
swift build
swift test
```

## License

MIT