From af17f9b17fa80c0f5150a857575ce94f537a62c2 Mon Sep 17 00:00:00 2001
From: Nikita Sin <74384266+lesleysin@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:41:29 +0200
Subject: [PATCH] feat: Introduce ElementChildRelation for node participation
 in the Duit element tree

- Added a new sealed class `ElementChildRelation` with stable numeric codes representing different child relationship types.
- Updated `index.dart` to export the new `element_child_relation.dart` file.
- Modified documentation in `descriptor.dart` to recommend using `ElementChildRelation` constants instead of raw integers for defining child relationships.
---
 lib/src/misc/element_child_relation.dart | 19 +++++++++++++++++++
 lib/src/misc/index.dart                  |  1 +
 lib/src/ui/descriptor.dart               |  6 +-----
 3 files changed, 21 insertions(+), 5 deletions(-)
 create mode 100644 lib/src/misc/element_child_relation.dart

diff --git a/lib/src/misc/element_child_relation.dart b/lib/src/misc/element_child_relation.dart
new file mode 100644
index 0000000..0e6d24a
--- /dev/null
+++ b/lib/src/misc/element_child_relation.dart
@@ -0,0 +1,19 @@
+/// Canonical numeric codes for how a node participates in the Duit element tree.
+///
+/// Values are stable wire-level integers (0–4); prefer these names over raw literals.
+sealed class ElementChildRelation {
+  /// No structural child slots (leaf nodes in the tree sense).
+  static const none = 0;
+
+  /// Exactly one structural child.
+  static const single = 1;
+
+  /// Multiple structural children.
+  static const multi = 2;
+
+  /// Component slot (merged template / component content).
+  static const component = 3;
+
+  /// Fragment slot (registered fragment subtree).
+  static const fragment = 4;
+}
diff --git a/lib/src/misc/index.dart b/lib/src/misc/index.dart
index 44ce035..8f65090 100644
--- a/lib/src/misc/index.dart
+++ b/lib/src/misc/index.dart
@@ -1,3 +1,4 @@
+export "element_child_relation.dart";
 export "script_runner.dart";
 export "logger/index.dart";
 export "parser.dart";
diff --git a/lib/src/ui/descriptor.dart b/lib/src/ui/descriptor.dart
index 8f78460..28789cb 100644
--- a/lib/src/ui/descriptor.dart
+++ b/lib/src/ui/descriptor.dart
@@ -35,11 +35,7 @@ final class WidgetDescriptor {
 
   /// Defines the child relationship pattern for this element type.
   ///
-  /// - `0`: No child elements (leaf widgets like Text, Image)
-  /// - `1`: Single child element (wrapper widgets like Container, Padding)
-  /// - `2`: Multiple child elements (layout widgets like Row, Column, Stack)
-  /// - `3`: Component content
-  /// - `4`: Fragment content
+  /// Prefer [ElementChildRelation] constants instead of raw integers.
   final int childRelation;
 
   /// Whether this element type is controlled by default.