citrine 0.2.0

data/lib/citrine.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Citrine — 信号式 Ruby UI 框架（黄水晶：水晶振荡器是信号源，命名致敬 Opal）
+# 设计定案见 GOALS.md 第七节：Signal 三宏 + block 级细粒度更新。
+# 本文件只加载平台无关核心；浏览器入口见 citrine/browser.rb。
+
+module Citrine
+  class << self
+    # 当前渲染器（由具体平台入口设置，如 citrine/dom.rb 的 DomRenderer）
+    attr_accessor :renderer
+
+    # 开发模式：只影响提示/诊断输出，不改变渲染语义。
+    # `bin/citrine dev` 打开的页面由 dev_server 注入 window.CITRINE_DEV 自动置位；
+    # CRuby 侧（SSR / 单测）可用 `Citrine.dev_mode = true` 手动打开。
+    attr_writer :dev_mode
+
+    def dev_mode?
+      !!@dev_mode
+    end
+
+    def mount(component, element)
+      raise "Citrine.renderer 未设置（浏览器入口应 require \"citrine/browser\"）" unless renderer
+
+      renderer.mount_component(component, element)
+    end
+
+    # 卸载一个已挂载的组件（会跑 on_unmount、解绑全局键盘、销毁所有 Effect）
+    def unmount(component)
+      root = component.respond_to?(:root) ? component.root : component
+      raise ArgumentError, "Citrine.unmount：组件尚未挂载（root 为空）" unless root
+
+      renderer = component.respond_to?(:renderer) && component.renderer ? component.renderer : self.renderer
+      raise "Citrine.unmount：找不到挂载这个组件的渲染器" unless renderer
+
+      renderer.unmount_component(root)
+    end
+
+    # render-to-string（纯 CRuby 可用）
+    def render(component)
+      require_relative "citrine/string_renderer"
+      StringRenderer.render(component)
+    end
+
+    # 批量窗口（S1-1）：块内对信号的多次写入合并为一轮 Effect 重跑，
+    # 中间态不进 DOM。事件处理器的分发过程已自动包裹一次；手动改多个信号
+    # 又不想看到级联重渲染时用：
+    #
+    #   Citrine.batch do
+    #     self.a = 1
+    #     self.b = 2      # a、b 的读者各只重跑一次
+    #   end
+    def batch(&block)
+      Scheduler.batch(&block)
+    end
+
+    # 造一个新信号。模块级工厂，哪儿都能用（领域模型 / 测试 / 组件外）：
+    #
+    #   tick = Citrine.signal(0)
+    #   rows = Citrine.signal { load_rows }   # 块 = 惰性初值，第一次读取时求值一次
+    #
+    # 存在的理由是"不让人写出裸的 `Signal`"——stdlib 与 Opal corelib 都有
+    # `::Signal`（进程信号），裸写会拿到那个类，报错完全不指向真因（FRICTION F14）。
+    # 普通类里想少打字可以 `include Citrine::Reactive`，得到同名实例方法。
+    def signal(value = nil, &init)
+      Signal.new(value, &init)
+    end
+
+    # 造一个响应式集合（D）：集合自身的每次变更都是一次通知，写法保持集合的样子。
+    #
+    #   rows = Citrine.signal_list([])
+    #   rows << row
+    #   rows.delete_at(0)
+    #
+    # get 返回**冻结**快照：`rows.get << x` 会当场 FrozenError，而不是静默不触发。
+    def signal_list(items = [])
+      ListSignal.new(items)
+    end
+  end
+end
+
+require_relative "citrine/version"
+require_relative "citrine/theme"
+require_relative "citrine/signal"
+require_relative "citrine/list_signal"
+require_relative "citrine/reactive"
+require_relative "citrine/key_event"
+require_relative "citrine/event"
+require_relative "citrine/sourcemap"
+require_relative "citrine/num"
+require_relative "citrine/node"
+require_relative "citrine/component"
+require_relative "citrine/renderer"

data/lib/rubocop/cop/citrine/no_raw_ivar_assignment.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Citrine
+      # Citrine 组件里的裸 @ivar 赋值绕过信号追踪——写入不会触发任何更新，
+      # 是"改了但界面不动"这类事故的根源（GOALS.md 第七节代价清单第 1 条）。
+      #
+      # 状态请用 `state` 宏（赋值即更新），跨渲染的派生值用 `computed`，
+      # 单次渲染内的中间值用局部变量。
+      #
+      #   class Counter < Citrine::Component
+      #     state :count, default: 0      # ✓
+      #     @cache = {}                   # ✗ 裸 ivar 赋值
+      #   end
+      #
+      # 只拦"写入"：裸读（@foo）在框架语义里无法区分，交由 code review。
+      class NoRawIvarAssignment < RuboCop::Cop::Base
+        MSG = "Citrine 组件内不要直接赋值 @ivar（绕过信号追踪）：状态用 state 宏，中间值用局部变量"
+
+        # 类体上的 @ivar 赋值（如宏实现的内部状态）不属于组件实例，不拦；
+        # 框架源码（lib/citrine/**）整体豁免，见 .rubocop.yml
+        def on_ivasgn(node)
+          return unless inside_component_scope?(node)
+
+          add_offense(node.loc.name)
+        end
+
+        private
+
+        # 词法上落在 Citrine::Component 子类（具名类或 Class.new(Citrine::Component)）
+        # 的**方法体**里的赋值。类体上的直接赋值是"组件类"状态（宏实现的内部
+        # 状态就是这种写法），不属于组件实例，不拦。
+        def inside_component_scope?(node)
+          node.each_ancestor(:class, :block).any? do |scope|
+            case scope.type
+            when :class
+              component_superclass?(scope.children[1]) && defined_in_method?(node, scope)
+            when :block
+              # (block (send Class :new <Component>) ...) → children[0] 是调用节点
+              class_new_component?(scope.children[0]) && defined_in_method?(node, scope)
+            else false
+            end
+          end
+        end
+
+        def defined_in_method?(node, class_scope)
+          method_scope = node.each_ancestor(:def, :defs).first
+          return false unless method_scope
+
+          # def 最近的词法作用域必须就是该组件作用域
+          #（匿名类没有 :class 节点，最近作用域是 Class.new 的 :block）
+          nearest = method_scope.each_ancestor(:class, :sclass, :module, :block).first
+          nearest&.equal?(class_scope)
+        end
+
+        def component_superclass?(superclass_node)
+          return false unless superclass_node&.const_type?
+
+          %w[Citrine::Component Component].include?(superclass_node.const_name)
+        end
+
+        def class_new_component?(send_node)
+          return false unless send_node&.method?(:new) && send_node.receiver&.const_type?
+          return false unless send_node.receiver.const_name == "Class"
+
+          base = send_node.arguments.first
+          base&.const_type? && %w[Citrine::Component Component].include?(base.const_name)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: citrine
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- ShiningRay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: opal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Citrine（黄水晶）：信号式响应 UI 框架。用纯 Ruby 写组件（state / computed 宏 + 赋值即更新），经 Opal
+  编译后渲染到浏览器 DOM、Canvas 与桌面（macOS .app）。水晶振荡器是信号的源头——名字致敬 Opal 开启的 Ruby→Web 宝石谱系。
+email:
+- shiningray@users.noreply.github.com
+executables:
+- citrine
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/citrine
+- desktop/main.swift
+- lib/citrine.rb
+- lib/citrine/browser.rb
+- lib/citrine/canvas.rb
+- lib/citrine/component.rb
+- lib/citrine/debug.rb
+- lib/citrine/dev_server.rb
+- lib/citrine/dom.rb
+- lib/citrine/event.rb
+- lib/citrine/key_event.rb
+- lib/citrine/list_signal.rb
+- lib/citrine/node.rb
+- lib/citrine/num.rb
+- lib/citrine/packager.rb
+- lib/citrine/reactive.rb
+- lib/citrine/renderer.rb
+- lib/citrine/signal.rb
+- lib/citrine/sourcemap.rb
+- lib/citrine/string_renderer.rb
+- lib/citrine/style.rb
+- lib/citrine/theme.rb
+- lib/citrine/version.rb
+- lib/rubocop/cop/citrine/no_raw_ivar_assignment.rb
+homepage: https://github.com/ShiningRay/citrine
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ShiningRay/citrine
+  changelog_uri: https://github.com/ShiningRay/citrine/blob/main/GOALS.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Signal-based reactive UI framework for Ruby, powered by Opal
+test_files: []