zaniah 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 615b3b2c2a4cd7f0cfc43138163f57ce0cab7fa5af420d24b69ce7b0ebaf62a7
-  data.tar.gz: f65f5cf0ec59f48c3320031e3ed1a4fc5bf60d97c2592810c74ca1537b866e91
+  metadata.gz: 0a864e71f3de289770aafa36f520440c0adab078b763412544bca3f9fb32cacb
+  data.tar.gz: fc0e6fb0c05f8d0769305954cc5a730258947845b8438328df6d66ca172e80ad
 SHA512:
-  metadata.gz: f3511cb3869208deb5870b407af6403da397e1776cb95ff44b6baedaee00248b05aa86e947bf5b9e78ed7b4eec98a79767e14e476195e6f1b928cbcbff5fb335
-  data.tar.gz: aabc636e94b51f64cf224473b1fd1214b791f029988c198246a81bd6d533487b65e27b5b960d19fc4b796c9502c311078e59482c83e7cf566d2942ccc60cbf7d
+  metadata.gz: 16ff7f0e3cc0ce444b502eaff32faaab6cf503af5bf0a4ad547a305aa9394c91d9960052e60bc94ce775521bd54e42ddadfff49b6f896147ca00771e3e4aa59f
+  data.tar.gz: 959e485686a3e92a155916a306afc0eb7848f6556d5c1bc6cbfe9c30a605701213dd37c79c978d49b807c60b25e9a47a3cc1e3fff9731cf0ae5a0432a7522f51

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.5.1 — 2026-09-16
+
+- Let lazy tree views accept externally loaded children and invalidate cached subtrees without blocking the UI thread.
+- Prevent replacement tree sources from inheriting stale lazy children.
+
 ## 0.5.0 — 2026-09-15
 
 - Make tree views lazy and viewport-virtualized while preserving stable-ID state across source rebuilds.

data/README.md

@@ -41,7 +41,7 @@ the drawing surface beneath the editor.
 - Stable-ID split-pane grids with fixed, fractional, and minmax tracks
 - OpenType shaping, font fallback, Japanese wrapping, text overlays, low-resolution text caching, selection, editing, and IME
 - Themes, state styles, keyed animation, springs, and reduced-motion support
-- Opt-in controls, overlays, tables, lazy viewport-virtualized trees, charts, forms, and terminal fallbacks
+- Opt-in controls, overlays, tables, externally completable lazy virtual trees, charts, forms, and terminal fallbacks
 - Spatial keyboard focus and a stable-ID, event-diffed cross-platform accessibility tree
 - F12 inspector, frame statistics, hot reload, and headless golden-image tests
 - Native input, IME, clipboard, file-drop, display, and filesystem events

data/docs/components.md

@@ -84,7 +84,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L3 | `DockPanel` | `(center:, top:, right:, bottom:, left:)` | five-region layout | group |
 | L3 | `ListView` | `(items, height:, row_height:, selected:)`; `on_select` | virtual rows and keyboard selection | list/listitem |
 | L4 | `Table`, `DataGrid` | `(rows, columns:, height:, selection:, row_key:)`; `on_sort`, `on_select`, `on_edit` | virtual rows, sorting, resizing, editing | table/row/cell |
-| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
 | L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
 | L5 | `LineChart`, `BarChart` | `(series, width:, height:, colors:, label:)` | axes, legend, tooltip | image |
 | L5 | `Validation` | `required`, `format`, `length`, `number`, `rule` | composable rules | n/a |
@@ -101,11 +101,18 @@ Table columns are hashes with `key`, and optional `label`, `width`, `sortable`,
 `resizable`, `editable`, and `render`. Tree items accept hashes containing `id`,
 `label`, and either an array or lazy proc in `children`. A lazy proc receives the
 item value, runs on first expansion, and is cached after it succeeds; a raised
-exception leaves it available for retry. IDs must be unique. Supply explicit,
-stable IDs and call `replace(items)` after changing the hierarchy to preserve
-selection, expansion, and successfully loaded children across a rebuilt source.
-Changing a loader while retaining its ID intentionally retains its cached children.
-Tree rows and accessibility nodes are built only for the current viewport.
+exception leaves it available for retry. A loader can return a placeholder while
+work runs elsewhere; call `replace_children(id, children)` on the UI thread to
+apply the result without changing selection, focus, or expansion. It returns
+`false` when the ID is missing or is not lazy. `invalidate(id)` likewise returns
+`false` for missing or non-lazy items; otherwise it discards that lazy result and
+its loaded descendants so the next expansion calls the loader again. Omit the ID
+to invalidate all loaded results. `replace(items)` starts a
+new source generation, so it never inherits loaded children from the old source.
+Completed children must be an array with unique, non-nil stable IDs, at most 64
+levels deep and 100,000 items total. Invalid results leave the previous children
+unchanged. Tree rows and accessibility nodes are built only for the current
+viewport.
 
 In a table, Up/Down/Home/End/Page keys move and select rows, Shift+Up/Down extends
 a range, and Cmd/Ctrl+A selects every row in multiple-selection mode. Sortable

data/lib/zaniah/ui/tree_view.rb

@@ -3,6 +3,10 @@
 module Zaniah
   module UI
     class TreeView < Component
+      MAX_COMPLETED_ITEMS = 100_000
+      MAX_DEPTH = 64
+      private_constant :MAX_COMPLETED_ITEMS, :MAX_DEPTH
+
       Item = Data.define(:id, :label, :value, :children, :loader, :parent, :depth)
       Segment = Data.define(:items, :first, :length, :parent, :depth, :path)
       Location = Data.define(:items, :index, :parent, :depth, :path)
@@ -25,15 +29,53 @@ module Zaniah
 
       def replace(items)
         wanted = @expanded.dup
-        @source, @locations = items.to_a, {}
-        @expanded.clear
-        reset_index
-        restore_expansions(wanted)
-        @selected_id = nil if !@selected_id.nil? && !visible_index(@selected_id)
+        @source = items.to_a
+        @loaded.clear
+        reindex(wanted)
+        clear_missing_selection
         @cx&.window&.request_frame
         self
       end
 
+      def replace_children(id, children)
+        item = find_known_item(id)
+        return false unless item&.loader
+
+        values = validate_children(id, children)
+        discard_descendants(id)
+        @loaded[id] = values
+        rebuild_segments
+        clear_missing_selection
+        @cx&.window&.request_frame
+        true
+      end
+
+      def invalidate(id = nil)
+        item = find_known_item(id) unless id.nil?
+        return false if !id.nil? && (!item&.loader || !@loaded.key?(id))
+
+        if id.nil?
+          return false if @loaded.empty?
+
+          @loaded.clear
+          reindex(@expanded.dup)
+        else
+          selected = @locations[@selected_id]
+          parent = @locations.fetch(id)
+          select_parent = selected && selected.path.length > parent.path.length &&
+            selected.path.first(parent.path.length) == parent.path
+          descendants = descendant_ids(id)
+          discard_descendants(id, descendants)
+          @loaded.delete(id)
+          @expanded.delete(id)
+          rebuild_segments
+          @selected_id = id if select_parent
+        end
+        clear_missing_selection
+        @cx&.window&.request_frame
+        true
+      end
+
       def build(cx)
         @cx = cx
         rebuild_segments if @indexed_expanded != @expanded
@@ -93,6 +135,74 @@ module Zaniah
 
       private
 
+      def reindex(wanted)
+        @locations = {}
+        @expanded.clear
+        reset_index
+        restore_expansions(wanted)
+      end
+
+      def clear_missing_selection
+        @selected_id = nil if !@selected_id.nil? && !visible_index(@selected_id)
+      end
+
+      def validate_children(id, children)
+        raise TypeError, "tree children must be an Array" unless children.is_a?(Array)
+
+        ids = {}
+        validate_collection(@source, [], ids, skip: id)
+        location = @locations.fetch(id)
+        validate_collection(children, location.path, ids, location.depth + 1, count: [0])
+        children
+      end
+
+      def validate_collection(items, path, ids, depth = 0, active = {}, skip: nil, count: nil)
+        raise ArgumentError, "tree children are too deeply nested" if depth > MAX_DEPTH
+        raise ArgumentError, "tree children must not contain cycles" if active[items.object_id]
+
+        active[items.object_id] = true
+        items.each_with_index do |source, index|
+          if count
+            count[0] += 1
+            raise ArgumentError, "tree children exceed #{MAX_COMPLETED_ITEMS} items" if count[0] > MAX_COMPLETED_ITEMS
+          end
+          pair = source.is_a?(Array) && source.length == 2 && source.last.is_a?(Array)
+          explicit_id = source.is_a?(Hash) ? source.key?(:id) : !pair && source.respond_to?(:id)
+          item_path = path + [index] unless explicit_id
+          item_id = source_id(source, item_path)
+          raise ArgumentError, "duplicate tree item id #{item_id.inspect}" if ids.key?(item_id)
+
+          ids[item_id] = true
+          next if item_id == skip
+          next if source.is_a?(Hash) ? !source.key?(:children) && !source.key?(:load) :
+            !(source.respond_to?(:children) || pair)
+
+          nested, loader = source_children(source)
+          raise TypeError, "tree item loader must respond to call" if loader && !loader.respond_to?(:call)
+
+          nested = @loaded.fetch(item_id, nested)
+          unless nested.empty?
+            item_path ||= path + [index]
+            validate_collection(nested, item_path, ids, depth + 1, active, skip: skip, count: count)
+          end
+        end
+      ensure
+        active.delete(items.object_id)
+      end
+
+      def descendant_ids(id)
+        location = @locations.fetch(id)
+        @locations.filter_map do |target, child|
+          target if child.path.length > location.path.length && child.path.first(location.path.length) == location.path
+        end
+      end
+
+      def discard_descendants(id, descendants = descendant_ids(id))
+        descendants.each { |target| @locations.delete(target) }
+        descendants.each { |target| @loaded.delete(target) }
+        @expanded.subtract(descendants)
+      end
+
       def reset_index
         @segments, @visible_count = [], 0
         append_segment(@source, 0, @source.length, nil, 0, [].freeze)
@@ -149,21 +259,18 @@ module Zaniah
 
       def normalize_item(source, parent, depth, path, items)
         path = path.freeze
+        children, loader = source_children(source)
         if source.is_a?(Hash)
-          children = source[:children]
-          loader = children.respond_to?(:call) ? children : source[:load]
           item = Item.new(id: source.fetch(:id, path), label: source.fetch(:label, source[:value]).to_s,
-            value: source.fetch(:value, source), children: loader.equal?(children) ? [] : Array(children),
+            value: source.fetch(:value, source), children: children,
             loader: loader, parent: parent, depth: depth)
         elsif source.is_a?(Array) && source.length == 2 && source.last.is_a?(Array)
           item = Item.new(id: path, label: source.first.to_s, value: source.first,
-            children: source.last, loader: nil, parent: parent, depth: depth)
+            children: children, loader: nil, parent: parent, depth: depth)
         else
-          children = source.children if source.respond_to?(:children)
-          loader = children if children.respond_to?(:call)
           item = Item.new(id: source.respond_to?(:id) ? source.id : path,
             label: source.respond_to?(:label) ? source.label.to_s : source.to_s,
-            value: source, children: loader ? [] : Array(children), loader: loader,
+            value: source, children: children, loader: loader,
             parent: parent, depth: depth)
         end
         raise ArgumentError, "tree item id must not be nil" if item.id.nil?
@@ -195,6 +302,19 @@ module Zaniah
         id
       end
 
+      def source_children(source)
+        if source.is_a?(Hash)
+          children = source[:children]
+          loader = children.respond_to?(:call) ? children : source[:load]
+        elsif source.is_a?(Array) && source.length == 2 && source.last.is_a?(Array)
+          return [source.last, nil]
+        else
+          children = source.children if source.respond_to?(:children)
+          loader = children if children.respond_to?(:call)
+        end
+        [loader.equal?(children) ? [] : Array(children), loader]
+      end
+
       def children_for(item) = @loaded.fetch(item.id, item.children)
       def expandable?(item) = !!(item.loader || !children_for(item).empty?)
       def branch(item) = expandable?(item) ? (@expanded.include?(item.id) ? "▾" : "▸") : " "
@@ -244,13 +364,22 @@ module Zaniah
         index && visible_item(index)
       end
 
+      def find_known_item(id)
+        location = @locations[id]
+        return find_item(id) unless location_valid?(id, location)
+
+        normalize_item(location.items[location.index], location.parent, location.depth, location.path, location.items)
+      end
+
       def toggle(id, value = nil)
         item = find_item(id)
         return false unless item && expandable?(item)
 
         open = value.nil? ? !@expanded.include?(id) : !!value
         return false if open == @expanded.include?(id)
-        @loaded[id] = Array(item.loader.call(item.value)) if open && item.loader && !@loaded.key?(id)
+        if open && item.loader && !@loaded.key?(id)
+          @loaded[id] = Array(item.loader.call(item.value))
+        end
         open ? @expanded.add(id) : @expanded.delete(id)
         rebuild_segments
         select_parent_after_collapse(item) unless open

data/lib/zaniah/version.rb

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

data/sig/ui.rbs

@@ -358,6 +358,8 @@ module Zaniah
       def expand: (untyped id) -> self
       def collapse: (untyped id) -> self
       def replace: (Array[untyped] items) -> self
+      def replace_children: (untyped id, Array[untyped] children) -> bool
+      def invalidate: (?untyped id) -> bool
       def accessibility_action: (Accessibility::Node node, Symbol action) -> bool?
     end
     class ListView < Component

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zaniah
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Yudai Takada