# 连线与布局

连线描述节点之间的关系。布局块用少量意图控制放置方式，而不暴露坐标或绘图原语。

## 连线方向

连线连接两个不同节点。允许前向引用，不允许自连线或使用分组作为端点。

| 操作符 | 含义                             |
| ------ | -------------------------------- |
| `->`   | 从左侧节点指向右侧节点的有向关系 |
| `<->`  | 双向对称的一个关系               |
| `--`   | 无方向或有意不指定方向的关联     |

`<->` 是一个关系，不是两条可独立标注连线的缩写。

## 连线种类与标签

可选标签描述协议、事件、命令、数据集或用途，长度为 1 至 40 个 Unicode scalar。可选 `kind` 与标签独立描述关系，默认值是 `flow`。

| Kind         | 预期含义                   |
| ------------ | -------------------------- |
| `flow`       | 通用运行时或概念流         |
| `request`    | 同步请求或调用             |
| `event`      | 异步消息或事件传递         |
| `data`       | 数据移动、复制、读取或写入 |
| `dependency` | 构建、部署或运维依赖       |

```stack
stack 1.0

diagram "Relationships" {
  node web "Web app" {
    kind client
  }

  node api "API"
  node queue "Events" {
    kind queue
  }

  edge web -> api "HTTPS" {
    kind request
  }

  edge api -> queue "OrderPlaced" {
    kind event
  }
}
```

表达不同关系时，同一对节点之间可以有多条连线。端点、操作符、标签和有效 kind 全部相同的精确重复无效。比较 `<->` 和 `--` 重复时忽略端点顺序。

## 布局作用域

一个图或分组最多包含一个 `layout` 块。分组中的布局只影响其直接子项，图中的布局只影响图的直接子项。`rank` 和 `order` 必须引用同一作用域中至少两个不同的直接子项。

布局把直接子分组视为一个项。不同分组后代节点之间的连线会形成直接子项之间的连接，因此即使分组不能作为连线端点，顶层布局仍可排列分组。

## Direction、rank 与 order

```stack
layout {
  direction right
  rank same [web, worker]
  order [web, worker, database]
}
```

- `direction right` 偏好从左到右，`direction down` 偏好从上到下。它是强提示，但不保证每条连线都朝该几何方向；嵌套分组不会继承。
- `rank same [a, b]` 是约束，要求列出的直接子项位于同一布局 rank。同一作用域中的一个子项不能出现在两个 same-rank 语句中。
- `order [a, b]` 是相对顺序提示。向右布局时按从上到下，向下布局时按从左到右，自动布局时沿选定 cross-axis 解释。可以省略其他子项。

为满足包含关系、same-rank 约束、可读性或输出边界，渲染器可以偏离 `order`。支持诊断的工具此时应发出 `STK4001`。

## 渲染器负责的决定

Stack 不提供坐标、尺寸、端口、路径、颜色、字体、换行或 z-index。渲染器负责防止重叠、保持包含与方向、确保标签可读、避开节点内部布线，并扩展画布而不裁剪语义内容。