zaniah 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ece04baf122d918de7ded4ab1ef943d1af3e50d85e23f9b496dafa77d8da3d7
-  data.tar.gz: 34777228a8ea17ea82cda2edcf76d74f4bec7cc3b6fca6728e01082caba8c43a
+  metadata.gz: 905d6e52f6013be2a7b8e0223ece509526a9cde3a6198c8386e8b59903bf2dde
+  data.tar.gz: 57db74ac492c60d4d0f310c25596005c89faa706e2c8750cb6322b8091ac3671
 SHA512:
-  metadata.gz: 9e9bf5c470a0c4f08c289a22472ae5e5df75c26d51cc9fb45d4896057d06f2bf727d72a409c9f5696e87ae38da3a3ecb32d993bf71c33d24d9c234aa3091e4ad
-  data.tar.gz: 52ceec0f227e76e2c8096bb5ec9224a3ec314da00d2e6513314ab7294eb406023c73967bc631d4dadf9aedd2931adb7cc38aaebef9f2b5f60e176b323e8075ae
+  metadata.gz: 27209b822cd741f79110228e9ddefc63eccf3eee8ffe64f2467570c4dd9fbc126176cf1e39289d8afa3b144577335809a1aa7b77d21deba013050e32eb374fcf
+  data.tar.gz: 739e4c67fd1de82b7fce3e0682aa9ecb1380cdf629f315f61387989f64d89379247840e6d691a36e0d17bb148a30a7eb5fa82cd5d749857b6592c864e2880340

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Add validated declarative element descriptions with event routing, tree diffs, and keyed surface reuse.
+
+## 0.6.0 — 2026-09-19
+
+- Add the validated declarative Describe layer for remote UI trees.
+
 ## 0.5.3 — 2026-09-17
 
 - Restore Ruby 4.0/json 3 compatibility for process messages and atlas caches while keeping JSON object additions disabled.

data/README.md

@@ -28,14 +28,15 @@ Zaniah is a pure Ruby UI toolkit for building desktop and terminal interfaces.
 It renders through native GPU APIs, a deterministic headless backend, or an ANSI
 terminal without extension compilation or a rendering subprocess.
 
-The name comes from the white ground laid before paint or gold leaf: Zaniah is
-the drawing surface beneath the editor.
+Zaniah is named for a star in Virgo. The toolkit is the drawing surface beneath
+the editor, providing the native rendering layer for its UI.
 
 ## Features
 
 - Flex, Grid, sticky, absolute, wrapping, and baseline-aware layouts
 - Gradients, transforms, paths, SVG, shadows, clipping, and GPU glyph atlases
 - Retained element state, subscriptions, and non-blocking background tasks
+- Validated declarative element trees with event IDs, minimal diffs, and keyed reuse
 - Scroll views, inertial input, and uniform or variable-height virtual lists
 - Stable-ID pointer and keyboard reordering without materializing virtual collections
 - Stable-ID split-pane grids with fixed, fractional, and minmax tracks
@@ -124,6 +125,7 @@ Native backends use the operating system libraries through Ruby's Fiddle. See
 - [Accessibility](docs/accessibility.md) — semantic trees, diffs, and native bridges
 - [Terminal UI](docs/tui.md) — deterministic component degradation
 - [CPU process workers](docs/process_pool.md) — portable background CPU work
+- [Declarative elements](docs/describe.md) — validated vocabularies, event routing, diffs, and surfaces
 - [Architecture decisions](docs/adr) — design records and rationale
 - [RBS declarations](sig) — public API signatures
 

data/docs/describe.md

@@ -0,0 +1,53 @@
+# Declarative elements
+
+`Zaniah::Describe` rebuilds element trees from plain data. The application owns
+the vocabulary, so it decides which node types and properties untrusted or
+remote producers may use.
+
+```ruby
+vocabulary = Zaniah::Describe::Vocabulary.build do
+  node :column, props: {gap: :integer} do |props, children|
+    Zaniah::Div.new.flex_col.gap(props.fetch(:gap)).children(children)
+  end
+
+  node :button,
+    props: {label: :string, on_click: :handler}, children: :none do |props|
+    Zaniah::UI::Button.new(props.fetch(:label)).on_click(&props.fetch(:on_click))
+  end
+end
+
+tree = {
+  "type" => "column",
+  "props" => {"gap" => 8},
+  "children" => [{
+    "type" => "button",
+    "props" => {"label" => "Save", "on_click" => ["save", 1]},
+    "children" => [],
+    "key" => "save"
+  }]
+}
+
+surface = Zaniah::Describe::Surface.new(
+  vocabulary: vocabulary,
+  on_event: ->(id, payload) { send_event(id, payload) }
+)
+surface.replace(tree)
+window.draw { surface.element }
+```
+
+Property validators include `:string`, `:integer`, `:number`, `:boolean`,
+`:array`, `:hash`, `:symbol`, `:handler`, `:any`, classes, callables, and arrays
+of allowed values. Children may be `:none`, `:one`, `:many`, an exact count,
+or a range. JSON string keys are normalized to symbols, and string values are
+normalized for symbol enums.
+
+Handler properties contain an opaque string or array ID. The factory receives
+a callable in its place; invoking it sends the ID and the first payload argument
+to `on_event`.
+
+`Zaniah::Describe.diff(previous, current)` returns `Patch` records with
+`:replace`, `:insert`, `:remove`, or `:update` operations. Paths are arrays of
+child indexes from the root, and `:update` contains the complete new property
+map. `Surface#apply` validates and applies a patch set atomically. Its `element`
+reader performs no building or I/O, and unchanged keyed subtrees retain their
+element instances across reordering.

data/lib/zaniah/describe.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+module Zaniah
+  module Describe
+    Node = Data.define(:type, :props, :children, :key)
+    Patch = Data.define(:op, :path, :node, :props)
+    MISSING = Object.new.freeze
+    private_constant :MISSING
+
+    class Vocabulary
+      Definition = Data.define(:props, :children, :factory)
+
+      def self.build(&block)
+        raise ArgumentError, "a vocabulary block is required" unless block
+        new.tap { |vocabulary| vocabulary.instance_eval(&block) }
+      end
+
+      def initialize
+        @definitions = {}
+      end
+
+      def node(type, props: {}, children: :many, &factory)
+        type = Describe.send(:normalize_type, type)
+        raise ArgumentError, "node #{type.inspect} is already registered" if @definitions.key?(type)
+        raise ArgumentError, "node #{type.inspect} needs a factory" unless factory
+
+        properties = Describe.send(:normalize_props, props)
+        properties.each_value { |validator| validate_validator!(validator) }
+        validate_children_rule!(children)
+        @definitions[type] = Definition.new(properties.freeze, children, factory)
+        self
+      end
+
+      def allow?(type)
+        @definitions.key?(Describe.send(:normalize_type, type))
+      rescue ArgumentError
+        false
+      end
+
+      def validate!(value)
+        node = Describe.send(:normalize_node, value)
+        validate_node!(node)
+      end
+
+      private
+
+      def definition(type)
+        @definitions.fetch(type) { raise ArgumentError, "node type #{type.inspect} is not allowed" }
+      end
+
+      def validate_node!(node)
+        entry = definition(node.type)
+        unknown = node.props.keys - entry.props.keys
+        raise ArgumentError, "unknown properties for #{node.type.inspect}: #{unknown.join(", ")}" unless unknown.empty?
+
+        props = node.props.each_with_object({}) do |(name, value), validated|
+          validator = entry.props.fetch(name)
+          value = normalize_property(validator, value)
+          raise ArgumentError, "invalid #{name.inspect} property for #{node.type.inspect}" unless valid_property?(validator, value)
+          validated[name] = value
+        end
+        children = node.children.map { |child| validate_node!(child) }.freeze
+        validated = Node.new(node.type, props.freeze, children, node.key)
+        validate_children!(entry.children, validated)
+        duplicate_keys = children.map(&:key).reject(&:nil?).tally.select { |_key, count| count > 1 }.keys
+        raise ArgumentError, "duplicate child keys for #{node.type.inspect}: #{duplicate_keys.inspect}" unless duplicate_keys.empty?
+        validated
+      end
+
+      def validate_children!(rule, node)
+        count = node.children.length
+        valid = case rule
+        when :none then count.zero?
+        when :one then count == 1
+        when :many then true
+        when Integer then count == rule
+        when Range then rule.cover?(count)
+        end
+        raise ArgumentError, "invalid child count for #{node.type.inspect}" unless valid
+      end
+
+      def validate_children_rule!(rule)
+        return if %i[none one many].include?(rule) || rule.is_a?(Integer) || rule.is_a?(Range)
+        raise ArgumentError, "children must be :none, :one, :many, an Integer, or a Range"
+      end
+
+      def validate_validator!(validator)
+        valid = validator.is_a?(Array) || validator.is_a?(Module) || validator.respond_to?(:call) ||
+          %i[any string integer number boolean array hash symbol handler].include?(validator)
+        raise ArgumentError, "unsupported property validator #{validator.inspect}" unless valid
+      end
+
+      def valid_property?(validator, value)
+        case validator
+        when :any then true
+        when :string then value.is_a?(String)
+        when :integer then value.is_a?(Integer)
+        when :number then value.is_a?(Numeric)
+        when :boolean then value == true || value == false
+        when :array then value.is_a?(Array)
+        when :hash then value.is_a?(Hash)
+        when :symbol then value.is_a?(Symbol)
+        when :handler then value.is_a?(String) || value.is_a?(Array)
+        when Array then validator.include?(value)
+        when Module then value.is_a?(validator)
+        else validator.call(value)
+        end
+      end
+
+      def normalize_property(validator, value)
+        return value.to_sym if validator == :symbol && value.is_a?(String)
+        if validator.is_a?(Array) && value.is_a?(String) && validator.any? { |item| item.is_a?(Symbol) }
+          symbol = value.to_sym
+          return symbol if validator.include?(symbol)
+        end
+        value
+      end
+
+      def build_node(node, children, on_event)
+        entry = definition(node.type)
+        props = node.props.each_with_object({}) do |(name, value), converted|
+          converted[name] = entry.props[name] == :handler ? event_handler(value, on_event) : value
+        end
+        element = entry.factory.call(props.freeze, children.freeze)
+        unless element.respond_to?(:request_layout) && element.respond_to?(:prepaint) && element.respond_to?(:paint)
+          raise TypeError, "factory for #{node.type.inspect} must return a renderable element"
+        end
+        element.key(node.key) if !node.key.nil? && element.respond_to?(:key)
+        element
+      end
+
+      def event_handler(id, on_event)
+        ->(payload = nil, *) { on_event.call(id, payload) }
+      end
+      private_constant :Definition
+    end
+
+    Mounted = Struct.new(:node, :element, :children)
+    private_constant :Mounted
+
+    class Surface
+      def initialize(vocabulary:, on_event:)
+        raise ArgumentError, "vocabulary must be a Vocabulary" unless vocabulary.is_a?(Vocabulary)
+        raise ArgumentError, "on_event must be callable" unless on_event.respond_to?(:call)
+        @vocabulary, @on_event = vocabulary, on_event
+      end
+
+      def replace(value)
+        if value.nil?
+          @node = @mounted = @element = nil
+        else
+          node = @vocabulary.validate!(value)
+          mounted = Describe.send(:mount, node, @vocabulary, @on_event, nil)
+          @node, @mounted, @element = node, mounted, mounted.element
+        end
+        self
+      end
+
+      def apply(values)
+        patches = Array(values).map { |value| Describe.send(:normalize_patch, value) }
+        candidate = patches.reduce(@node) { |node, patch| Describe.send(:apply_patch, node, patch) }
+        candidate = @vocabulary.validate!(candidate) if candidate
+        mounted = candidate && Describe.send(:mount, candidate, @vocabulary, @on_event, @mounted)
+        @node, @mounted, @element = candidate, mounted, mounted&.element
+        self
+      end
+
+      def element = @element
+      def empty? = @element.nil?
+    end
+
+    class << self
+      def build(value, vocabulary:, on_event:)
+        raise ArgumentError, "vocabulary must be a Vocabulary" unless vocabulary.is_a?(Vocabulary)
+        raise ArgumentError, "on_event must be callable" unless on_event.respond_to?(:call)
+        node = vocabulary.validate!(value)
+        mount(node, vocabulary, on_event, nil).element
+      end
+
+      def diff(previous, current)
+        previous = normalize_node(previous) if previous
+        current = normalize_node(current) if current
+        return [] if previous == current
+        return [Patch.new(:insert, [].freeze, current, nil)] unless previous
+        return [Patch.new(:remove, [].freeze, nil, nil)] unless current
+
+        [].tap { |patches| diff_node(previous, current, [], patches) }
+      end
+
+      private
+
+      def normalize_type(type)
+        raise ArgumentError, "node type must be a Symbol or String" unless type.is_a?(Symbol) || type.is_a?(String)
+        type.to_sym
+      end
+
+      def normalize_props(value)
+        raise ArgumentError, "props must be a Hash" unless value.is_a?(Hash)
+        value.each_with_object({}) do |(key, item), props|
+          raise ArgumentError, "property names must be Symbols or Strings" unless key.is_a?(Symbol) || key.is_a?(String)
+          name = key.to_sym
+          raise ArgumentError, "duplicate property #{name.inspect}" if props.key?(name)
+          props[name] = item
+        end
+      end
+
+      def normalize_node(value)
+        return Node.new(value.type, normalize_props(value.props).freeze,
+          normalize_children(value.children), value.key) if value.is_a?(Node)
+        raise ArgumentError, "node must be a Describe::Node or Hash" unless value.is_a?(Hash)
+
+        keys = value.keys.map { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+        unknown = keys - %i[type props children key]
+        raise ArgumentError, "unknown node fields: #{unknown.inspect}" unless unknown.empty?
+        type = fetch_field(value, :type)
+        props = fetch_field(value, :props, {})
+        children = fetch_field(value, :children, [])
+        key = fetch_field(value, :key, nil)
+        Node.new(normalize_type(type), normalize_props(props).freeze, normalize_children(children), key)
+      end
+
+      def normalize_children(value)
+        raise ArgumentError, "children must be an Array" unless value.is_a?(Array)
+        value.map { |child| normalize_node(child) }.freeze
+      end
+
+      def fetch_field(hash, name, default = MISSING)
+        return hash[name] if hash.key?(name)
+        string = name.to_s
+        return hash[string] if hash.key?(string)
+        raise ArgumentError, "node is missing #{name.inspect}" if default.equal?(MISSING)
+        default
+      end
+
+      def mount(node, vocabulary, on_event, previous)
+        return previous if previous&.node == node
+
+        previous_children = previous&.children || []
+        keyed = previous_children.each_with_object({}) do |mounted, by_key|
+          key = mounted.node.key
+          by_key[[mounted.node.type, key]] = mounted unless key.nil?
+        end
+        children = node.children.each_with_index.map do |child, index|
+          match = if child.key.nil?
+            previous_children[index] if previous_children[index]&.node&.key.nil?
+          else
+            keyed[[child.type, child.key]]
+          end
+          mount(child, vocabulary, on_event, match)
+        end
+        element = vocabulary.send(:build_node, node, children.map(&:element), on_event)
+        Mounted.new(node, element, children)
+      end
+
+      def diff_node(previous, current, path, patches)
+        unless previous.type == current.type && previous.key == current.key
+          patches << Patch.new(:replace, path.freeze, current, nil)
+          return
+        end
+        patches << Patch.new(:update, path.freeze, nil, current.props) unless previous.props == current.props
+        diff_children(previous.children, current.children, path, patches)
+      end
+
+      def diff_children(previous, current, path, patches)
+        working = previous.dup
+        index = 0
+        while index < current.length
+          wanted = current[index]
+          present = working[index]
+          if present && same_slot?(present, wanted)
+            diff_node(present, wanted, path + [index], patches)
+            working[index] = wanted
+            index += 1
+          elsif present&.key && !current[index..].any? { |node| same_slot?(present, node) }
+            patches << Patch.new(:remove, (path + [index]).freeze, nil, nil)
+            working.delete_at(index)
+          elsif wanted.key && (from = working.each_index.find { |at| at > index && same_slot?(working[at], wanted) })
+            patches << Patch.new(:remove, (path + [from]).freeze, nil, nil)
+            working.delete_at(from)
+            patches << Patch.new(:insert, (path + [index]).freeze, wanted, nil)
+            working.insert(index, wanted)
+            index += 1
+          elsif wanted.key || present.nil?
+            patches << Patch.new(:insert, (path + [index]).freeze, wanted, nil)
+            working.insert(index, wanted)
+            index += 1
+          else
+            diff_node(present, wanted, path + [index], patches)
+            working[index] = wanted
+            index += 1
+          end
+        end
+        (working.length - 1).downto(current.length) do |at|
+          patches << Patch.new(:remove, (path + [at]).freeze, nil, nil)
+        end
+      end
+
+      def same_slot?(left, right)
+        if !left.key.nil? || !right.key.nil?
+          !left.key.nil? && left.key == right.key
+        else
+          left.type == right.type
+        end
+      end
+
+      def normalize_patch(value)
+        return Patch.new(normalize_operation(value.op), normalize_path(value.path),
+          value.node && normalize_node(value.node), value.props && normalize_props(value.props).freeze) if value.is_a?(Patch)
+        raise ArgumentError, "patch must be a Describe::Patch or Hash" unless value.is_a?(Hash)
+        op = normalize_operation(fetch_patch_field(value, :op))
+        path = normalize_path(fetch_patch_field(value, :path))
+        node = fetch_patch_field(value, :node, nil)
+        props = fetch_patch_field(value, :props, nil)
+        Patch.new(op, path, node && normalize_node(node), props && normalize_props(props).freeze)
+      end
+
+      def fetch_patch_field(hash, name, default = MISSING)
+        return hash[name] if hash.key?(name)
+        return hash[name.to_s] if hash.key?(name.to_s)
+        raise ArgumentError, "patch is missing #{name.inspect}" if default.equal?(MISSING)
+        default
+      end
+
+      def normalize_operation(value)
+        raise ArgumentError, "patch operation must be a Symbol or String" unless value.is_a?(Symbol) || value.is_a?(String)
+        value.to_sym
+      end
+
+      def normalize_path(value)
+        raise ArgumentError, "patch path must be an Array" unless value.is_a?(Array)
+        value.map do |index|
+          index = Integer(index)
+          raise ArgumentError, "patch path indexes must be non-negative" if index.negative?
+          index
+        end.freeze
+      end
+
+      def apply_patch(root, patch)
+        raise ArgumentError, "unknown patch operation #{patch.op.inspect}" unless %i[replace insert remove update].include?(patch.op)
+        case patch.op
+        when :replace
+          raise ArgumentError, "replace patch needs a node" unless patch.node
+          return patch.node if patch.path.empty?
+          rewrite_at(root, patch.path) { |_node| patch.node }
+        when :insert
+          raise ArgumentError, "insert patch needs a node" unless patch.node
+          return patch.node if patch.path.empty? && root.nil?
+          change_children(root, patch.path, insert: patch.node)
+        when :remove
+          return nil if patch.path.empty?
+          change_children(root, patch.path, remove: true)
+        when :update
+          raise ArgumentError, "update patch needs props" unless patch.props
+          rewrite_at(root, patch.path) { |node| node.with(props: patch.props) }
+        end
+      end
+
+      def rewrite_at(node, path, &block)
+        raise ArgumentError, "patch path does not exist" unless node
+        return yield(node) if path.empty?
+        index = path.first
+        raise ArgumentError, "patch path does not exist" unless index < node.children.length
+        children = node.children.dup
+        children[index] = rewrite_at(children[index], path.drop(1), &block)
+        node.with(children: children.freeze)
+      end
+
+      def change_children(root, path, insert: nil, remove: false)
+        raise ArgumentError, "insert and remove require a child path" if path.empty?
+        index = path.last
+        rewrite_at(root, path[0...-1]) do |parent|
+          children = parent.children.dup
+          if remove
+            raise ArgumentError, "patch path does not exist" unless index < children.length
+            children.delete_at(index)
+          else
+            raise ArgumentError, "patch insertion is outside the children" unless index <= children.length
+            children.insert(index, insert)
+          end
+          parent.with(children: children.freeze)
+        end
+      end
+    end
+  end
+end

data/lib/zaniah/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zaniah
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/lib/zaniah.rb

@@ -37,6 +37,7 @@ require_relative "zaniah/process_pool"
 require_relative "zaniah/input"
 require_relative "zaniah/drag_drop"
 require_relative "zaniah/element"
+require_relative "zaniah/describe"
 Zaniah.autoload(:SVG, File.expand_path("zaniah/svg", __dir__))
 require_relative "zaniah/scroll_state"
 require_relative "zaniah/scroll_view"

data/sig/describe.rbs

@@ -0,0 +1,44 @@
+module Zaniah
+  module Describe
+    type node_input = Node | Hash[Symbol | String, untyped]
+    type patch_input = Patch | Hash[Symbol | String, untyped]
+    type event_callback = ^(untyped id, untyped payload) -> untyped
+
+    class Node < Data
+      attr_reader type: Symbol
+      attr_reader props: Hash[Symbol, untyped]
+      attr_reader children: Array[Node]
+      attr_reader key: untyped
+      def self.new: (Symbol type, Hash[Symbol, untyped] props, Array[Node] children, untyped key) -> Node
+                  | (type: Symbol, props: Hash[Symbol, untyped], children: Array[Node], key: untyped) -> Node
+    end
+
+    class Patch < Data
+      attr_reader op: :replace | :insert | :remove | :update
+      attr_reader path: Array[Integer]
+      attr_reader node: Node?
+      attr_reader props: Hash[Symbol, untyped]?
+      def self.new: (:replace | :insert | :remove | :update op, Array[Integer] path, Node? node, Hash[Symbol, untyped]? props) -> Patch
+                  | (op: :replace | :insert | :remove | :update, path: Array[Integer], node: Node?, props: Hash[Symbol, untyped]?) -> Patch
+    end
+
+    class Vocabulary
+      def self.build: () { (Vocabulary) -> void } -> Vocabulary
+      def initialize: () -> void
+      def node: (Symbol | String type, ?props: Hash[Symbol | String, untyped], ?children: :none | :one | :many | Integer | Range[Integer]) { (Hash[Symbol, untyped] props, Array[_Renderable] children) -> _Renderable } -> self
+      def allow?: (Symbol | String type) -> bool
+      def validate!: (node_input value) -> Node
+    end
+
+    def self.build: (node_input value, vocabulary: Vocabulary, on_event: event_callback) -> _Renderable
+    def self.diff: (node_input? previous, node_input? current) -> Array[Patch]
+
+    class Surface
+      def initialize: (vocabulary: Vocabulary, on_event: event_callback) -> void
+      def replace: (node_input? value) -> self
+      def apply: (Array[patch_input] patches) -> self
+      def element: () -> _Renderable?
+      def empty?: () -> bool
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zaniah
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Yudai Takada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alhena
@@ -87,6 +87,7 @@ files:
 - docs/adr/README.md
 - docs/animation.md
 - docs/components.md
+- docs/describe.md
 - docs/drag_drop.md
 - docs/gallery/command-palette-dark.png
 - docs/gallery/command-palette-high_contrast.png
@@ -195,6 +196,7 @@ files:
 - lib/zaniah/configuration.rb
 - lib/zaniah/corners.rb
 - lib/zaniah/data_compat.rb
+- lib/zaniah/describe.rb
 - lib/zaniah/device_pixels.rb
 - lib/zaniah/devtools.rb
 - lib/zaniah/devtools/hot_reload.rb
@@ -360,6 +362,7 @@ files:
 - sig/accessibility.rbs
 - sig/animation.rbs
 - sig/app.rbs
+- sig/describe.rbs
 - sig/devtools.rbs
 - sig/drag_drop.rbs
 - sig/elements.rbs