@retikz/react 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/es/index.d.ts

@@ -8,10 +8,10 @@
  */
 export { Tikz, Node, Path, Step, Text } from './kernel';
 export type { TikzProps, NodeProps, PathProps, StepProps, TextProps } from './kernel';
-export { Draw } from './sugar';
-export type { DrawProps } from './sugar';
+export { Draw, EdgeLabel } from './sugar';
+export type { DrawProps, EdgeLabelProps } from './sugar';
 export { DrawWay } from '@retikz/core';
-export type { WayItem, WayDSL, WayCycle, WayVia } from '@retikz/core';
+export type { WayItem, WayDSL, WayCycle, WayVia, WayRelItem, WayLabel, WayLabelOp, } from '@retikz/core';
 export { buildIR as convertReactNodeToIR } from './kernel/_builder';
 export { convertIRToReactNode } from './kernel/_unbuilder';
 //# sourceMappingURL=index.d.ts.map

package/dist/es/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtF,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAEtF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/es/index.js

@@ -6,7 +6,8 @@ import { Step } from "./kernel/Step.js";
 import { Text } from "./kernel/Text.js";
 import "./kernel/index.js";
 import { Draw } from "./sugar/Draw.js";
+import { EdgeLabel } from "./sugar/EdgeLabel.js";
 import "./sugar/index.js";
 import { convertIRToReactNode } from "./kernel/_unbuilder.js";
 import { DrawWay } from "@retikz/core";
-export { Draw, DrawWay, Node, Path, Step, Text, Tikz, convertIRToReactNode, buildIR as convertReactNodeToIR };
+export { Draw, DrawWay, EdgeLabel, Node, Path, Step, Text, Tikz, convertIRToReactNode, buildIR as convertReactNodeToIR };

package/dist/es/kernel/Path.d.ts

@@ -8,6 +8,12 @@ export type PathProps = {
     strokeWidth?: IRPath['strokeWidth'];
     /** SVG stroke-dasharray 模式（如 "4 2"） */
     strokeDasharray?: IRPath['strokeDasharray'];
+    /** 端点形状（SVG `stroke-linecap`）：`'butt'`（默认 / 直角）/ `'round'`（半圆）/ `'square'`（方头外扩半 stroke） */
+    lineCap?: IRPath['lineCap'];
+    /** 拐点形状（SVG `stroke-linejoin`）：`'miter'`（默认 / 尖角）/ `'round'`（圆角）/ `'bevel'`（切角） */
+    lineJoin?: IRPath['lineJoin'];
+    /** 语义 stroke 档位（TikZ `ultra thin` … `ultra thick`）；显式 `strokeWidth` 始终优先 */
+    thickness?: IRPath['thickness'];
     /**
      * 路径级箭头方向。`'->'` = 终点；`'<-'` = 起点；`'<->'` = 两端；
      * 省略或 `'none'` = 无箭头。
@@ -22,6 +28,12 @@ export type PathProps = {
     fill?: IRPath['fill'];
     /** SVG fill-rule：`'nonzero'`（默认）/ `'evenodd'`（环形 / 孔洞） */
     fillRule?: IRPath['fillRule'];
+    /** 整 path 透明度 0~1；同时作用于 stroke 与 fill */
+    opacity?: IRPath['opacity'];
+    /** 仅 fill 透明度 0~1 */
+    fillOpacity?: IRPath['fillOpacity'];
+    /** 仅 stroke 透明度 0~1（TikZ `draw opacity`） */
+    drawOpacity?: IRPath['drawOpacity'];
     /** 应当全部是 <Step /> */
     children: ReactNode;
 };

package/dist/es/kernel/Path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Path.d.ts","sourceRoot":"","sources":["../../../src/kernel/Path.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,uBAAuB;AACvB,MAAM,MAAM,SAAS,GAAG;IACtB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1B,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC5C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAClC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,qBAAqB;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC,SAAS,CAAc,CAAC"}
+{"version":3,"file":"Path.d.ts","sourceRoot":"","sources":["../../../src/kernel/Path.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,uBAAuB;AACvB,MAAM,MAAM,SAAS,GAAG;IACtB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1B,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC5C,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAClC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,qBAAqB;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,qBAAqB;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC,SAAS,CAAc,CAAC"}

package/dist/es/kernel/Step.d.ts

@@ -1,9 +1,14 @@
-import { FC } from 'react';
-import { IRTarget } from '@retikz/core';
+import { FC, ReactNode } from 'react';
+import { IRControlPoint, IRStepLabel, IRTarget } from '@retikz/core';
 /**
  * <Step> 组件的 props。
- * v0.1.0-alpha.1 支持四种 kind：'move' / 'line' / 'step'（折角）/ 'cycle'（闭合）。
+ * alpha.3 起支持十种 kind：'move' / 'line' / 'step'（折角）/ 'cycle'（闭合）/
+ * 'curve'（二次贝塞尔）/ 'cubic'（三次贝塞尔）/ 'bend'（弧形简记）/
+ * 'arc'（圆弧段）/ 'circlePath'（整圆）/ 'ellipsePath'（整椭圆）。
  * kind 默认 'line'。
+ *
+ * ADR-0004：除 'move' / 'cycle' 外的八种 kind 都可挂 `label?: IRStepLabel` 边标注；
+ * 等价的写法是用 sugar `<EdgeLabel>` 当 children。两者并存时 prop 优先。
  */
 export type StepProps = {
     /** 移动游标但不绘制（类似 SVG path "M"） */
@@ -15,6 +20,10 @@ export type StepProps = {
     kind?: 'line';
     /** 直线终点 */
     to: IRTarget;
+    /** 边标注（ADR-0004），等价于 <EdgeLabel> child */
+    label?: IRStepLabel;
+    /** sugar 形态：`<Step><EdgeLabel>...</EdgeLabel></Step>`；其它 children 静默忽略 */
+    children?: ReactNode;
 } | {
     /** 折角段：从游标经一个直角拐点到目标点（TikZ `-|` / `|-`） */
     kind: 'step';
@@ -22,9 +31,83 @@ export type StepProps = {
     via: '-|' | '|-';
     /** 折角终点 */
     to: IRTarget;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
 } | {
     /** 闭合：把当前子路径回到最近一个 move 起点（TikZ `cycle` / SVG `Z`） */
     kind: 'cycle';
+} | {
+    /** 二次贝塞尔：一个控制点（TikZ `.. controls (B) ..`） */
+    kind: 'curve';
+    /** 控制点（alpha.3 仅支持 [x, y]，未来可能扩展） */
+    control: IRControlPoint;
+    /** 曲线终点 */
+    to: IRTarget;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
+} | {
+    /** 三次贝塞尔：两个控制点（TikZ `.. controls (B) and (C) ..`） */
+    kind: 'cubic';
+    /** 第一控制点（影响起点切线） */
+    control1: IRControlPoint;
+    /** 第二控制点（影响终点切线） */
+    control2: IRControlPoint;
+    /** 曲线终点 */
+    to: IRTarget;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
+} | {
+    /** 弧形简记：按方向 + 角度生成 cubic（TikZ `to[bend left=N]` / `to[bend right=N]`） */
+    kind: 'bend';
+    /** 弯向：'left' / 'right'（视觉左右，相对 from→to） */
+    bendDirection: 'left' | 'right';
+    /** 弯角度（度），缺省 30 */
+    bendAngle?: number;
+    /** 终点 */
+    to: IRTarget;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
+} | {
+    /** 弧段：以游标为圆心，按起末角度 + 半径绘制（TikZ `arc[start angle=…, end angle=…, radius=…]`） */
+    kind: 'arc';
+    /** 弧的起始角度（度），CCW from +x（注意 retikz polar y 轴向下，角度 90 视觉朝下） */
+    startAngle: number;
+    /** 弧的终止角度（度） */
+    endAngle: number;
+    /** 弧的半径 */
+    radius: number;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
+} | {
+    /** 整圆：以游标为圆心，按半径绘制；画完画笔留在圆心 */
+    kind: 'circlePath';
+    /** 圆的半径 */
+    radius: number;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
+} | {
+    /** 整椭圆：以游标为圆心，按 x/y 轴半径绘制；画完画笔留在圆心 */
+    kind: 'ellipsePath';
+    /** 椭圆 x 轴半径 */
+    radiusX: number;
+    /** 椭圆 y 轴半径 */
+    radiusY: number;
+    /** 边标注（ADR-0004） */
+    label?: IRStepLabel;
+    /** sugar 形态 */
+    children?: ReactNode;
 };
 /**
  * Step 是 DSL 标记组件——本身不渲染。

package/dist/es/kernel/Step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../src/kernel/Step.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,EAAE,EAAE,QAAQ,CAAC;CACd,GACD;IACE,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW;IACX,EAAE,EAAE,QAAQ,CAAC;CACd,GACD;IACE,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IACjB,WAAW;IACX,EAAE,EAAE,QAAQ,CAAC;CACd,GACD;IACE,sDAAsD;IACtD,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEN;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC,SAAS,CAAc,CAAC"}
+{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../src/kernel/Step.tsx"],"names":[],"mappings":"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"}

package/dist/es/kernel/_builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_builder.d.ts","sourceRoot":"","sources":["../../../src/kernel/_builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAkB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAE,EAAE,EAA+C,MAAM,cAAc,CAAC;AA6NpF;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,UAAU,SAAS,KAAG,EAI5C,CAAC"}
+{"version":3,"file":"_builder.d.ts","sourceRoot":"","sources":["../../../src/kernel/_builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAkB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EACV,EAAE,EAQH,MAAM,cAAc,CAAC;AAkXtB;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,UAAU,SAAS,KAAG,EAI5C,CAAC"}

package/dist/es/kernel/_builder.js

@@ -1,6 +1,6 @@
 import { TIKZ_NODE, TIKZ_PATH } from "./_displayNames.js";
 import { Children, isValidElement } from "react";
-import { CURRENT_IR_VERSION } from "@retikz/core";
+import { CURRENT_IR_VERSION, parseTargetSugar } from "@retikz/core";
 //#region src/kernel/_builder.ts
 /** 取 React 元素 type 上的 displayName；type 为字符串时直接返回，用于识别 Kernel/Sugar 组件 */
 var getDisplayName = (el) => {
@@ -105,6 +105,33 @@ var buildNode = (props) => ({
 	font: props.font
 });
 /**
+* 扫描 Step children，把首个 <EdgeLabel> 翻译为 IRStepLabel；
+* 非字符串 children 静默跳过；多个 <EdgeLabel> 取首个。
+*/
+var readEdgeLabel = (children) => {
+	let result;
+	Children.forEach(children, (child) => {
+		if (result !== void 0) return;
+		if (!isValidElement(child)) return;
+		if (getDisplayName(child) !== "@retikz/EdgeLabel") return;
+		const props = child.props;
+		if (typeof props.children !== "string") return;
+		const out = { text: props.children };
+		if (props.position !== void 0) out.position = props.position;
+		if (props.side !== void 0) out.side = props.side;
+		result = out;
+	});
+	return result;
+};
+/**
+* 解析 Step 的 label 来源：prop `label` 优先于 sugar `<EdgeLabel>` child；
+* 都缺省时返回 undefined。
+*/
+var resolveStepLabel = (props) => {
+	if (props.label !== void 0) return props.label;
+	return readEdgeLabel(props.children);
+};
+/**
 * 扫描 <Path> children 收集 <Step> 序列。
 * 至少 2 段；首段不是 move 时强制改为 move（与 SVG path 的 "M …" 语义对齐）；
 * cycle 没有 to 字段，若用户把 cycle 放在首段，coerce 时降级到 move (0,0)。
@@ -123,32 +150,109 @@ var readPathChildren = (children) => {
 			});
 			return;
 		}
+		const label = kind === "move" ? void 0 : resolveStepLabel(props);
 		if (kind === "step") {
-			out.push({
+			const step = {
 				type: "step",
 				kind: "step",
 				via: props.via,
-				to: props.to
+				to: parseTargetSugar(props.to)
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "curve") {
+			const step = {
+				type: "step",
+				kind: "curve",
+				to: parseTargetSugar(props.to),
+				control: props.control
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "cubic") {
+			const step = {
+				type: "step",
+				kind: "cubic",
+				to: parseTargetSugar(props.to),
+				control1: props.control1,
+				control2: props.control2
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "bend") {
+			const step = {
+				type: "step",
+				kind: "bend",
+				to: parseTargetSugar(props.to),
+				bendDirection: props.bendDirection
+			};
+			if (props.bendAngle !== void 0) step.bendAngle = props.bendAngle;
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "arc") {
+			const step = {
+				type: "step",
+				kind: "arc",
+				startAngle: props.startAngle,
+				endAngle: props.endAngle,
+				radius: props.radius
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "circlePath") {
+			const step = {
+				type: "step",
+				kind: "circlePath",
+				radius: props.radius
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "ellipsePath") {
+			const step = {
+				type: "step",
+				kind: "ellipsePath",
+				radiusX: props.radiusX,
+				radiusY: props.radiusY
+			};
+			if (label) step.label = label;
+			out.push(step);
+			return;
+		}
+		if (kind === "move") {
+			out.push({
+				type: "step",
+				kind: "move",
+				to: parseTargetSugar(props.to)
 			});
 			return;
 		}
-		out.push({
+		const step = {
 			type: "step",
-			kind,
-			to: props.to
-		});
+			kind: "line",
+			to: parseTargetSugar(props.to)
+		};
+		if (label) step.label = label;
+		out.push(step);
 	});
 	if (out.length < 2) throw new Error("<Path> requires at least 2 <Step> children");
 	if (out[0].kind !== "move") {
 		const first = out[0];
-		out[0] = first.kind === "cycle" ? {
+		out[0] = {
 			type: "step",
 			kind: "move",
-			to: [0, 0]
-		} : {
-			type: "step",
-			kind: "move",
-			to: first.to
+			to: first.kind === "cycle" || first.kind === "arc" || first.kind === "circlePath" || first.kind === "ellipsePath" ? [0, 0] : first.to
 		};
 	}
 	return out;
@@ -159,10 +263,16 @@ var buildPath = (props) => ({
 	stroke: props.stroke,
 	strokeWidth: props.strokeWidth,
 	strokeDasharray: props.strokeDasharray,
+	lineCap: props.lineCap,
+	lineJoin: props.lineJoin,
+	thickness: props.thickness,
 	arrow: props.arrow,
 	arrowShape: props.arrowShape,
 	fill: props.fill,
 	fillRule: props.fillRule,
+	opacity: props.opacity,
+	fillOpacity: props.fillOpacity,
+	drawOpacity: props.drawOpacity,
 	children: readPathChildren(props.children)
 });
 /**

package/dist/es/kernel/_displayNames.d.ts

@@ -6,4 +6,6 @@ export declare const TIKZ_PATH = "@retikz/Path";
 export declare const TIKZ_STEP = "@retikz/Step";
 /** <Text> 组件的 displayName（Node 内多行文本带样式） */
 export declare const TIKZ_TEXT = "@retikz/Text";
+/** <EdgeLabel> 组件的 displayName（Step 内边标注，ADR-0004） */
+export declare const TIKZ_EDGE_LABEL = "@retikz/EdgeLabel";
 //# sourceMappingURL=_displayNames.d.ts.map

package/dist/es/kernel/_displayNames.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_displayNames.d.ts","sourceRoot":"","sources":["../../../src/kernel/_displayNames.ts"],"names":[],"mappings":"AAKA,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,4CAA4C;AAC5C,eAAO,MAAM,SAAS,iBAAiB,CAAC"}
+{"version":3,"file":"_displayNames.d.ts","sourceRoot":"","sources":["../../../src/kernel/_displayNames.ts"],"names":[],"mappings":"AAKA,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,6BAA6B;AAC7B,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,4CAA4C;AAC5C,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,sDAAsD;AACtD,eAAO,MAAM,eAAe,sBAAsB,CAAC"}

package/dist/es/kernel/_displayNames.js

@@ -7,5 +7,7 @@ var TIKZ_PATH = "@retikz/Path";
 var TIKZ_STEP = "@retikz/Step";
 /** <Text> 组件的 displayName（Node 内多行文本带样式） */
 var TIKZ_TEXT = "@retikz/Text";
+/** <EdgeLabel> 组件的 displayName（Step 内边标注，ADR-0004） */
+var TIKZ_EDGE_LABEL = "@retikz/EdgeLabel";
 //#endregion
-export { TIKZ_NODE, TIKZ_PATH, TIKZ_STEP, TIKZ_TEXT };
+export { TIKZ_EDGE_LABEL, TIKZ_NODE, TIKZ_PATH, TIKZ_STEP, TIKZ_TEXT };

package/dist/es/kernel/_unbuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_unbuilder.d.ts","sourceRoot":"","sources":["../../../src/kernel/_unbuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,EAAE,EAA2B,MAAM,cAAc,CAAC;AA8EhE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,EAAE,KAAG,SACW,CAAC"}
+{"version":3,"file":"_unbuilder.d.ts","sourceRoot":"","sources":["../../../src/kernel/_unbuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,EAAE,EAA2B,MAAM,cAAc,CAAC;AA2JhE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,EAAE,KAAG,SACW,CAAC"}

package/dist/es/kernel/_unbuilder.js

@@ -47,12 +47,63 @@ var stepToElement = (step, key) => {
 		key,
 		kind: "step",
 		via: step.via,
+		to: step.to,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "curve") return createElement(Step, {
+		key,
+		kind: "curve",
+		to: step.to,
+		control: step.control,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "cubic") return createElement(Step, {
+		key,
+		kind: "cubic",
+		to: step.to,
+		control1: step.control1,
+		control2: step.control2,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "bend") return createElement(Step, {
+		key,
+		kind: "bend",
+		to: step.to,
+		bendDirection: step.bendDirection,
+		...step.bendAngle !== void 0 && { bendAngle: step.bendAngle },
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "arc") return createElement(Step, {
+		key,
+		kind: "arc",
+		startAngle: step.startAngle,
+		endAngle: step.endAngle,
+		radius: step.radius,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "circlePath") return createElement(Step, {
+		key,
+		kind: "circlePath",
+		radius: step.radius,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "ellipsePath") return createElement(Step, {
+		key,
+		kind: "ellipsePath",
+		radiusX: step.radiusX,
+		radiusY: step.radiusY,
+		...step.label !== void 0 && { label: step.label }
+	});
+	if (step.kind === "move") return createElement(Step, {
+		key,
+		kind: "move",
 		to: step.to
 	});
 	return createElement(Step, {
 		key,
 		kind: step.kind,
-		to: step.to
+		to: step.to,
+		...step.label !== void 0 && { label: step.label }
 	});
 };
 /** discriminated union 兜底：编译期保证不漏 case，运行时给出明确错误 */
@@ -71,10 +122,16 @@ var childToElement = (child, key) => {
 			stroke: child.stroke,
 			strokeWidth: child.strokeWidth,
 			strokeDasharray: child.strokeDasharray,
+			lineCap: child.lineCap,
+			lineJoin: child.lineJoin,
+			thickness: child.thickness,
 			arrow: child.arrow,
 			arrowShape: child.arrowShape,
 			fill: child.fill,
 			fillRule: child.fillRule,
+			opacity: child.opacity,
+			fillOpacity: child.fillOpacity,
+			drawOpacity: child.drawOpacity,
 			children: child.children.map((s, j) => stepToElement(s, j))
 		});
 		default: return assertNever(child);

package/dist/es/sugar/Draw.d.ts

@@ -2,7 +2,13 @@ import { FC } from 'react';
 import { IRPath, WayDSL } from '@retikz/core';
 /** <Draw> 组件的 props */
 export type DrawProps = {
-    /** way 数组 DSL：节点 id / 坐标 / 极坐标 / 折角算子 `'-|'` `'|-'` / 闭合 `DrawWay.cycle` */
+    /**
+     * way 数组 DSL：节点 id / 笛卡尔 / 极坐标 / 相对偏移 `{ position, type: DrawWay.Relative | DrawWay.Accumulate }` /
+     * 折角算子 `'-|'` `'|-'`（或 `DrawWay.Hv` / `DrawWay.Vh`）/ 闭合 `DrawWay.Cycle` /
+     * 曲线算子 `{ curve | cubic | bend }`（infix）/
+     * 形状算子 `{ arc | circle | ellipse }`（infix，以"上一项"为圆心，不消耗下一项）/
+     * 边标注算子 `{ label }`（infix，修饰下一段）
+     */
     way: WayDSL;
     /** 描边色，省略时用 currentColor */
     stroke?: IRPath['stroke'];
@@ -10,6 +16,12 @@ export type DrawProps = {
     strokeWidth?: IRPath['strokeWidth'];
     /** SVG stroke-dasharray 模式（如 "4 2"） */
     strokeDasharray?: IRPath['strokeDasharray'];
+    /** 端点形状（SVG `stroke-linecap`） */
+    lineCap?: IRPath['lineCap'];
+    /** 拐点形状（SVG `stroke-linejoin`） */
+    lineJoin?: IRPath['lineJoin'];
+    /** 语义 stroke 档位（TikZ `ultra thin` … `ultra thick`）；显式 `strokeWidth` 始终优先 */
+    thickness?: IRPath['thickness'];
     /**
      * 路径级箭头方向。`'->'` = 终点；`'<-'` = 起点；`'<->'` = 两端；
      * 省略或 `'none'` = 无箭头。
@@ -19,10 +31,16 @@ export type DrawProps = {
      * 箭头形状。默认 `'normal'`。其他：`'open'` / `'stealth'` / `'diamond'` / `'circle'`。
      */
     arrowShape?: IRPath['arrowShape'];
-    /** 闭合区域填充色，省略 = 不填充。配合 way 末尾的 `DrawWay.cycle` 画填充形状 */
+    /** 闭合区域填充色，省略 = 不填充。配合 way 末尾的 `DrawWay.Cycle` 画填充形状 */
     fill?: IRPath['fill'];
     /** SVG fill-rule：`'nonzero'`（默认）/ `'evenodd'` */
     fillRule?: IRPath['fillRule'];
+    /** 整 path 透明度 0~1 */
+    opacity?: IRPath['opacity'];
+    /** 仅 fill 透明度 0~1 */
+    fillOpacity?: IRPath['fillOpacity'];
+    /** 仅 stroke 透明度 0~1（TikZ `draw opacity`） */
+    drawOpacity?: IRPath['drawOpacity'];
 };
 /**
  * Sugar 组件——展开为等价的 <Path><Step.../></Path> Kernel 子树。

package/dist/es/sugar/Draw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Draw.d.ts","sourceRoot":"","sources":["../../../src/sugar/Draw.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAKnD,uBAAuB;AACvB,MAAM,MAAM,SAAS,GAAG;IACtB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1B,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC5C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAClC,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC,SAAS,CAsB9B,CAAC"}
+{"version":3,"file":"Draw.d.ts","sourceRoot":"","sources":["../../../src/sugar/Draw.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAKnD,uBAAuB;AACvB,MAAM,MAAM,SAAS,GAAG;IACtB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1B,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC5C,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAClC,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,qBAAqB;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IACpC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC,SAAS,CA0G9B,CAAC"}

package/dist/es/sugar/Draw.js

@@ -12,15 +12,21 @@ import { jsx } from "react/jsx-runtime";
 * （useState / useMemo / useEffect 等会抛 "Invalid hook call"）。
 */
 var Draw = (props) => {
-	const { way, stroke, strokeWidth, strokeDasharray, arrow, arrowShape, fill, fillRule } = props;
+	const { way, stroke, strokeWidth, strokeDasharray, lineCap, lineJoin, thickness, arrow, arrowShape, fill, fillRule, opacity, fillOpacity, drawOpacity } = props;
 	return /* @__PURE__ */ jsx(Path, {
 		stroke,
 		strokeWidth,
 		strokeDasharray,
+		lineCap,
+		lineJoin,
+		thickness,
 		arrow,
 		arrowShape,
 		fill,
 		fillRule,
+		opacity,
+		fillOpacity,
+		drawOpacity,
 		children: parseWay(way).map((s, i) => {
 			if (s.kind === "cycle") return /* @__PURE__ */ jsx(Step, { kind: "cycle" }, i);
 			if (s.kind === "move") return /* @__PURE__ */ jsx(Step, {
@@ -30,11 +36,59 @@ var Draw = (props) => {
 			if (s.kind === "step") return /* @__PURE__ */ jsx(Step, {
 				kind: "step",
 				via: s.via,
-				to: s.to
+				to: s.to,
+				label: s.label
+			}, i);
+			if (s.kind === "curve") return /* @__PURE__ */ jsx(Step, {
+				kind: "curve",
+				to: s.to,
+				control: s.control,
+				label: s.label
+			}, i);
+			if (s.kind === "cubic") return /* @__PURE__ */ jsx(Step, {
+				kind: "cubic",
+				to: s.to,
+				control1: s.control1,
+				control2: s.control2,
+				label: s.label
+			}, i);
+			if (s.kind === "bend") {
+				if (s.bendAngle !== void 0) return /* @__PURE__ */ jsx(Step, {
+					kind: "bend",
+					to: s.to,
+					bendDirection: s.bendDirection,
+					bendAngle: s.bendAngle,
+					label: s.label
+				}, i);
+				return /* @__PURE__ */ jsx(Step, {
+					kind: "bend",
+					to: s.to,
+					bendDirection: s.bendDirection,
+					label: s.label
+				}, i);
+			}
+			if (s.kind === "arc") return /* @__PURE__ */ jsx(Step, {
+				kind: "arc",
+				startAngle: s.startAngle,
+				endAngle: s.endAngle,
+				radius: s.radius,
+				label: s.label
+			}, i);
+			if (s.kind === "circlePath") return /* @__PURE__ */ jsx(Step, {
+				kind: "circlePath",
+				radius: s.radius,
+				label: s.label
+			}, i);
+			if (s.kind === "ellipsePath") return /* @__PURE__ */ jsx(Step, {
+				kind: "ellipsePath",
+				radiusX: s.radiusX,
+				radiusY: s.radiusY,
+				label: s.label
 			}, i);
 			return /* @__PURE__ */ jsx(Step, {
 				kind: "line",
-				to: s.to
+				to: s.to,
+				label: s.label
 			}, i);
 		})
 	});

package/dist/es/sugar/EdgeLabel.d.ts

@@ -0,0 +1,20 @@
+import { FC } from 'react';
+import { IRStepLabel } from '@retikz/core';
+/** <EdgeLabel> 组件的 props（ADR-0004） */
+export type EdgeLabelProps = {
+    /** 段上位置（TikZ `midway` / `near start` / `near end`），缺省 'midway' */
+    position?: IRStepLabel['position'];
+    /** 相对段方向 / 视觉方位的偏移侧（'sloped' = 沿切线旋转），缺省 'above' */
+    side?: IRStepLabel['side'];
+    /** 标签文字内容；必须是字符串 */
+    children: string;
+};
+/**
+ * Sugar 组件——挂在 <Step> 内作为子节点声明边标注。等价于在 Step 上写
+ * `label={{ text, position, side }}` prop；二者并存时 prop 优先。
+ *
+ * <EdgeLabel> 自身不渲染，由 buildIR 在收集 Step 时识别 displayName 后
+ * 提取到 IR `step.label`。
+ */
+export declare const EdgeLabel: FC<EdgeLabelProps>;
+//# sourceMappingURL=EdgeLabel.d.ts.map

package/dist/es/sugar/EdgeLabel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeLabel.d.ts","sourceRoot":"","sources":["../../../src/sugar/EdgeLabel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACnC,oDAAoD;IACpD,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,cAAc,CAAc,CAAC"}

package/dist/es/sugar/EdgeLabel.js

@@ -0,0 +1,13 @@
+import { TIKZ_EDGE_LABEL } from "../kernel/_displayNames.js";
+//#region src/sugar/EdgeLabel.tsx
+/**
+* Sugar 组件——挂在 <Step> 内作为子节点声明边标注。等价于在 Step 上写
+* `label={{ text, position, side }}` prop；二者并存时 prop 优先。
+*
+* <EdgeLabel> 自身不渲染，由 buildIR 在收集 Step 时识别 displayName 后
+* 提取到 IR `step.label`。
+*/
+var EdgeLabel = () => null;
+EdgeLabel.displayName = TIKZ_EDGE_LABEL;
+//#endregion
+export { EdgeLabel };