view_component_atomix 0.1.0

data/lib/view_component/atomix/accessors.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    module Accessors
+      ACCESSOR_SUFFIX = /_(styles?|theme|vars|variables)\z/.freeze
+
+      def styles_method(name = nil)
+        return current_styles_method if name.nil?
+
+        @_styles_method_explicit = true
+        install_styles_method(name)
+      end
+
+      private
+
+      def install_styles_method(name)
+        name = name.to_sym
+        previous = current_styles_method
+        if previous && previous != name
+          singleton_class.send(:undef_method, previous) if singleton_class.method_defined?(previous)
+          undef_method(previous) if method_defined?(previous)
+        end
+
+        define_singleton_method(name) { |definitions = nil, &block| define_styles(definitions, &block) }
+        define_method(name) { self.class.send(:resolved_styles) }
+        @_styles_method = name
+        invalidate_styles
+        styles_mixins.each { |mod| define_mixin_accessors(mod) }
+        name
+      end
+
+      def current_styles_method
+        return @_styles_method if defined?(@_styles_method)
+
+        is_a?(Class) && superclass.respond_to?(:styles_method) ? superclass.styles_method : nil
+      end
+
+      def styles_method_explicit?
+        defined?(@_styles_method_explicit) && @_styles_method_explicit
+      end
+
+      def styles_mixins
+        @_styles_mixins ||= []
+      end
+
+      def inherited_styles_mixin_accessors
+        return {} unless is_a?(Class) && superclass.respond_to?(:styles_mixin_accessors, true)
+
+        superclass.send(:styles_mixin_accessors)
+      end
+
+      # Separate readers select the last included module. Once a reader is
+      # the primary accessor, its modules are represented by inherited_styles
+      # instead, including any declarations which override them on that owner.
+      def styles_mixin_accessors
+        accessors = inherited_styles_mixin_accessors
+        styles_mixins.each do |mod|
+          accessors[styles_accessor_for(mod)] = mod if mod < Variables
+        end
+        accessors.delete(current_styles_method)
+        accessors
+      end
+
+      def accessor_base(mod)
+        mod.name.underscore.tr("/", "_").sub(ACCESSOR_SUFFIX, "")
+      end
+
+      def styles_accessor_for(mod)
+        return mod.styles_method if mod.name.nil? || mod.send(:styles_method_explicit?)
+
+        :"#{accessor_base(mod)}_styles"
+      end
+
+      def theme_accessor_for(mod)
+        return :theme if mod.name.nil?
+
+        :"#{accessor_base(mod)}_theme"
+      end
+
+      def companion_styles_module
+        return styles_state.companion_styles_module if styles_state.companion_styles_module
+        return unless is_a?(Class) && name
+
+        candidate = "#{name}Styles".safe_constantize
+        return unless candidate.instance_of?(Module) && candidate < Base
+
+        styles_state.companion_styles_module = candidate
+      end
+
+      def companion_styles
+        mod = companion_styles_module
+        mod && mod < Variables ? mod.send(:resolved_styles) : Sheet::EMPTY
+      end
+
+      def companion_theme
+        mod = companion_styles_module
+        mod && mod < Theme ? mod.send(:resolved_theme) : Style::EMPTY
+      end
+
+      def add_styles_mixin(mod)
+        styles_mixins << mod
+        invalidate_styles
+        define_mixin_accessors(mod)
+      end
+
+      def define_mixin_accessors(mod)
+        if mod < Variables
+          accessor = styles_accessor_for(mod)
+          unless accessor == current_styles_method
+            define_singleton_method(accessor) { mod.send(:resolved_styles) }
+            define_method(accessor) { mod.send(:resolved_styles) }
+
+            leaked = mod.styles_method
+            undef_method(leaked) if leaked != accessor && leaked != current_styles_method && method_defined?(leaked)
+          end
+        end
+
+        return unless mod < Theme
+
+        accessor = theme_accessor_for(mod)
+        return if accessor == :theme
+
+        define_singleton_method(accessor) { mod.send(:resolved_theme) }
+        define_method(accessor) { mod.send(:resolved_theme) }
+      end
+    end
+  end
+end

data/lib/view_component/atomix/attribute_helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    module AttributeHelpers
+      def sx(*styles)
+        ViewComponent::Atomix.sx(*styles)
+      end
+
+      def sx_attrs(*styles)
+        ViewComponent::Atomix.props(*styles)
+      end
+    end
+  end
+end

data/lib/view_component/atomix/attrs.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    class Attrs < Hash
+      def to_s
+        html = map { |name, value| "#{name}=\"#{ERB::Util.html_escape(value)}\"" }.join(" ")
+        ActiveSupport::SafeBuffer.new(html)
+      end
+      alias to_str to_s
+
+      def html_safe?
+        true
+      end
+    end
+  end
+end

data/lib/view_component/atomix/base.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    module Base
+      extend ActiveSupport::Concern
+
+      included do
+        ViewComponent::Atomix.includers << self
+        extend Mixin unless is_a?(Class)
+      end
+
+      class_methods do
+        include Accessors
+        include ThemeResolution
+
+        private
+
+        def styles_state
+          @_styles_state ||= OwnerState.new
+        end
+
+        def reset_styles!
+          styles_state.reset!
+        end
+
+        def invalidate_styles_cache!
+          styles_state.invalidate!
+        end
+
+        def unload_styles!
+          styles_state.unload!
+        end
+
+        def styles_unloaded?
+          styles_state.unloaded?
+        end
+
+        def define_styles(definitions = nil, &block)
+          return resolved_styles if definitions.nil? && block.nil?
+
+          unless self < ViewComponent::Atomix
+            raise ArgumentError, "#{self} includes ViewComponent::Atomix::Variables only. " \
+                                 "Include ViewComponent::Atomix to declare traits."
+          end
+
+          source = block ? block.source_location.first : caller_locations(2, 1).first.path
+          styles_resolution_monitor.synchronize do
+            styles_state.styles << DeclarationQueue::StyleDeclaration.new(block: block || proc { definitions }, source: source)
+            invalidate_styles
+          end
+          nil
+        end
+
+        def invalidate_styles
+          ViewComponent::Atomix.invalidate_caches!
+        end
+
+        def resolved_styles
+          resolve_owner(:styles) do |reentrant|
+            reentrant ? compile_pending_vars : compile_pending_styles
+            styles_context
+          end
+        end
+
+        def resolve_owner(kind)
+          cached = kind == :styles ? styles_state.styles_resolved : styles_state.theme_resolved
+          return cached if cached
+
+          styles_resolution_monitor.synchronize do
+            ResolutionSession.with do |session|
+              resolving = :"#{kind}_resolving"
+              cache = :"#{kind}_resolved"
+              if styles_state.public_send(resolving)
+                session.provisional!
+                return session.nested { yield true }
+              end
+              cached = styles_state.public_send(cache)
+              return cached if cached
+
+              outermost = !session.resolving?
+              result = nil
+              # An outer read gets one fresh cache-building pass after active
+              # dependencies unwind. Successful declarations remain consumed.
+              2.times do
+                provisional = false
+                session.frame do |frame|
+                  # Immediate style_vars can drain deferred variables outside a
+                  # styles read. Their in-progress owner is provisional too.
+                  session.provisional! if kind == :styles && styles_state.variables_resolving
+                  styles_state.public_send(:"#{resolving}=", true)
+                  begin
+                    result = resolve_stable(frame) { yield false }
+                    provisional = frame.provisional
+                    styles_state.public_send(:"#{cache}=", result) unless provisional
+                  rescue StandardError
+                    styles_state.public_send(:"#{cache}=", nil)
+                    raise
+                  ensure
+                    styles_state.public_send(:"#{resolving}=", false)
+                  end
+                end
+                break unless outermost && provisional
+
+                outermost = false
+              end
+              result
+            end
+          end
+        end
+
+        def styles_resolution_monitor
+          RESOLUTION_MONITOR
+        end
+
+        # Dependencies can declare more work on this owner while its context is
+        # being assembled. Never overwrite their invalidation with a stale sheet.
+        def resolve_stable(frame)
+          ResolutionSession::MAX_STABILITY_PASSES.times do
+            frame.stale = false
+            result = yield
+            return result unless frame.stale
+
+            ResolutionSession.with(&:consume!)
+          end
+          raise ArgumentError, "Style dependencies keep changing during resolution"
+        end
+
+        def inherited_styles
+          return Sheet::EMPTY unless is_a?(Class) && superclass.respond_to?(:resolved_styles, true)
+
+          superclass.send(:resolved_styles)
+        end
+
+        def compile_pending_styles
+          compile_pending_vars
+          styles_state.styles.drain do |declaration|
+            ViewComponent::Atomix.registry.with_source(declaration.source) do
+              definitions, breakpoints = Builder.evaluate(self, declaration.block)
+              sheet = commit_owner_declaration do
+                previous_breakpoints = styles_state.styles_breakpoints
+                begin
+                  add_breakpoints(breakpoints)
+                  Compiler.compile(definitions, name: name || "anonymous", context: styles_context,
+                                   breakpoints: styles_breakpoints)
+                rescue StandardError
+                  styles_state.styles_breakpoints = previous_breakpoints
+                  raise
+                end
+              end
+              merge_own_styles(sheet)
+            end
+          end
+        rescue StandardError
+          styles_state.styles_resolved = nil
+          raise
+        end
+
+        def compile_pending_vars
+          previous = styles_state.variables_resolving
+          styles_state.variables_resolving = true
+          styles_state.variables.drain do |declaration|
+            ViewComponent::Atomix.registry.with_source(declaration.source) do
+              definitions = declaration.block.call
+              add_vars(declaration.label, definitions)
+            end
+          end
+        rescue StandardError
+          styles_state.styles_resolved = nil
+          raise
+        ensure
+          styles_state.variables_resolving = previous
+        end
+
+        def merge_own_styles(sheet)
+          styles_state.styles_own = styles_state.styles_own ? styles_state.styles_own.merge(sheet) : sheet
+        end
+
+        def add_breakpoints(map)
+          return if map.empty?
+
+          # Inherited queries remain inherited so later parent declarations
+          # cannot be shadowed by a snapshot taken on this owner.
+          styles_state.styles_breakpoints = (styles_state.styles_breakpoints || {}).merge(map)
+        end
+
+        def styles_breakpoints
+          inherited = if is_a?(Class) && superclass.respond_to?(:styles_breakpoints, true)
+                        superclass.send(:styles_breakpoints)
+                      else
+                        {}
+                      end
+          inherited.merge(styles_state.styles_breakpoints || {})
+        end
+
+        def styles_context
+          matching_mixins = styles_mixins.select { |mod| mod < Variables && styles_accessor_for(mod) == current_styles_method }
+          inherited_mixin = inherited_styles_mixin_accessors[current_styles_method]
+          layers = [inherited_styles, inherited_mixin ? inherited_mixin.send(:resolved_styles) : Sheet::EMPTY,
+                    companion_styles, *matching_mixins.map { |mod| mod.send(:resolved_styles) },
+                    styles_state.styles_own || Sheet::EMPTY]
+          layers.reduce(Sheet::EMPTY, :merge)
+        end
+
+        # Owner results survive a consuming transaction's failure, so their CSS
+        # must commit independently. Keep user block evaluation outside this
+        # boundary; publish the compiled result on the owner only
+        # after it succeeds. Source attribution remains around both phases.
+        def commit_owner_declaration(&block)
+          ViewComponent::Atomix.registry.transaction(independent: true, &block)
+        end
+
+        def add_vars(label, definitions)
+          vars = commit_owner_declaration { Vars.new(label, definitions) }
+          merge_own_styles(Sheet.new({}, vars.names.keys.to_h { |key| [key, vars] }))
+        end
+
+        def macro_label(name)
+          return name.to_s if name
+
+          self.name || "anonymous:#{caller_locations(2, 1).first&.then { |l| "#{l.path}:#{l.lineno}" }}"
+        end
+      end
+    end
+  end
+end

data/lib/view_component/atomix/builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    class Builder
+      attr_reader :definitions, :declared_breakpoints
+
+      def initialize(owner)
+        @owner = owner
+        @definitions = {}
+        @declared_breakpoints = {}
+      end
+
+      def breakpoints(**map)
+        Atomix.config.validate_breakpoints!(map)
+        @declared_breakpoints.merge!(map)
+        nil
+      end
+
+      def trait(name, *args, **definition)
+        raise ArgumentError, "trait name must be a Symbol, got #{name.inspect}" unless name.is_a?(Symbol)
+        raise ArgumentError, "trait #{name.inspect} is already declared in this block" if @definitions.key?(name)
+
+        @definitions[name] = build_definition(name, args, definition)
+        nil
+      end
+
+      def self.evaluate(owner, block)
+        builder = new(owner)
+        returned = builder.instance_exec(&block)
+        definitions = builder.definitions
+        if definitions.empty?
+          unless returned.nil? || returned.is_a?(Hash)
+            raise ArgumentError, "styles block must declare traits or return a Hash, got #{returned.class}"
+          end
+
+          definitions = returned || {}
+        elsif returned.is_a?(Hash)
+          raise ArgumentError, "styles block must either declare traits or return a Hash, not both"
+        end
+
+        [definitions, builder.declared_breakpoints]
+      end
+
+      private
+
+      def build_definition(name, args, definition)
+        merged = {}
+        args.each do |arg|
+          case arg
+          when Symbol then merged[arg] = true
+          when Hash then merged.merge!(arg)
+          when Proc
+            raise ArgumentError, "trait #{name.inspect} cannot combine a lambda with other definitions" unless args.one? && definition.empty?
+
+            return arg
+          else
+            raise ArgumentError, "trait #{name.inspect} accepts trait symbols, a Hash, or a lambda, got #{arg.inspect}"
+          end
+        end
+        merged.merge!(definition)
+      end
+
+      def method_missing(name, *args, **kwargs, &block)
+        if @owner&.respond_to?(name)
+          @owner.public_send(name, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @owner&.respond_to?(name) || super
+      end
+    end
+  end
+end

data/lib/view_component/atomix/compiler.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    class Compiler
+      def self.compile(definitions, name:, context: Sheet::EMPTY, breakpoints: {})
+        Atomix.registry.transaction { new(name, context, breakpoints).compile(definitions) }
+      end
+
+      def initialize(name, context = Sheet::EMPTY, breakpoints = {})
+        @name = name
+        @context = context
+        @conditions = Atomix.config.condition_resolver(Atomix.config.breakpoints.merge(breakpoints))
+        @sets = {}
+        @classifier = TraitClassifier.new(sets: @sets, inherited_sets: context.sets, conditions: @conditions)
+      end
+
+      def compile(definitions)
+        unless definitions.is_a?(Hash)
+          raise ArgumentError, "Style definitions must be a Hash of traits, got #{definitions.class}"
+        end
+
+        definitions.each do |set_name, definition|
+          set_name = set_name.to_sym
+          @sets[set_name] = compile_set(set_name, definition)
+        end
+        Sheet.new(@sets)
+      end
+
+      private
+
+      def compile_set(set_name, definition)
+        result = @classifier.classify(set_name, definition)
+        case result.kind
+        when :dynamic
+          DynamicStyle.new(name: @name, set: set_name, fn: result.fn, properties: result.properties)
+        when :enumerated
+          compile_enumerated(set_name, result.members, result.default)
+        when :combination
+          compile_combination(set_name, result.references, result.properties)
+        when :plain
+          compile_style(result.properties)
+        end
+      end
+
+      def lookup(key)
+        @sets[key] || (@context.sets[key] if @context.sets.key?(key))
+      end
+
+      def compile_enumerated(set_name, members, default)
+        members.each do |member, styles|
+          condition = styles.keys.find { |key| @conditions.condition?(key) && !@conditions.pseudo_element?(key) }
+          next unless condition
+
+          raise ArgumentError,
+                "Enumerated member #{member.inspect} in trait #{set_name.inspect} contains condition #{condition.inspect}. " \
+                "Conditions must be nested under a property. If #{member.inspect} was intended as a property, check its spelling."
+        end
+        compiled = members.to_h { |member, styles| [member, compile_style(styles)] }
+        if default
+          default = default.to_sym
+          unless compiled.key?(default)
+            raise ArgumentError,
+                  "Default #{default.inspect} is not a member of trait #{set_name.inspect}. " \
+                  "Members: #{compiled.keys.inspect}"
+          end
+        end
+        EnumeratedStyle.new(name: set_name, members: compiled, default: default)
+      end
+
+      def compile_combination(set_name, references, properties)
+        styles = references.map { |key, value| resolve_reference(set_name, key, value) }
+        styles << compile_style(properties) if properties.any?
+        Atomix.merge(*styles)
+      end
+
+      def resolve_reference(set_name, key, value)
+        target = lookup(key)
+        case target
+        when EnumeratedStyle
+          if value == true
+            raise ArgumentError, "Trait #{key.inspect} in #{set_name.inspect} is enumerated; pass a member such as #{key}: #{target.member_names.first.inspect}" if target.default.nil?
+            target.call
+          else
+            target.call(value)
+          end
+        when DynamicStyle
+          raise ArgumentError, "Trait #{set_name.inspect} cannot reference the dynamic trait #{key.inspect}"
+        else
+          unless value == true
+            raise ArgumentError, "Trait #{key.inspect} in #{set_name.inspect} is not enumerated; use #{key}: true or :#{key}"
+          end
+          target
+        end
+      end
+
+      def compile_style(definition)
+        classes = {}
+
+        definition.each do |key, value|
+          if @conditions.pseudo_element?(key)
+            condition = @conditions.resolve(key)
+            unless value.is_a?(Hash)
+              raise ArgumentError, "Pseudo-element #{key.inspect} must map to a Hash of properties"
+            end
+
+            value.each do |prop_key, prop_value|
+              property = Property.normalize_key(prop_key)
+              classes["#{condition}#{property}"] = compile_property(property, prop_value, [condition])
+            end
+          elsif @conditions.condition?(key)
+            raise ArgumentError,
+                  "Condition #{key.inspect} must be nested under a property, e.g. " \
+                  "color: { default: \"red\", #{key.inspect} => \"blue\" }"
+          else
+            property = Property.normalize_key(key)
+            classes[property] = compile_property(property, value, [])
+          end
+        end
+
+        Style.new(classes)
+      end
+
+      def compile_property(property, value, conditions)
+        case value
+        when nil
+          conditions.empty? ? nil : []
+        when Hash
+          value.flat_map do |key, nested|
+            if key == :default
+              Array(compile_property(property, nested, conditions))
+            else
+              compile_property(property, nested, conditions + [@conditions.resolve(key)])
+            end
+          end
+        else
+          normalized = Property.normalize_value(property, value)
+          class_name = Hashing.class_name(property, normalized, conditions)
+          Atomix.registry.add(
+            Rule.new(selector: ".#{class_name}", property: property, value: normalized, conditions: conditions)
+          )
+          [class_name]
+        end
+      end
+    end
+  end
+end

data/lib/view_component/atomix/condition_resolver.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Atomix
+    # One effective condition vocabulary per compilation. Variables use the
+    # global map; component traits include their locally declared breakpoints.
+    class ConditionResolver
+      attr_reader :breakpoints, :pseudo_map
+
+      def initialize(breakpoints:, pseudo_map:)
+        self.class.validate_pseudo_map!(pseudo_map)
+        self.class.validate_breakpoints!(breakpoints, pseudo_map: pseudo_map)
+        @breakpoints = Immutable.copy(breakpoints)
+        @pseudo_map = Immutable.copy(pseudo_map)
+      end
+
+      def breakpoint?(key)
+        key.is_a?(Symbol) && breakpoints.key?(key)
+      end
+
+      def condition?(key)
+        case key
+        when String then key.start_with?(":", "@")
+        when Symbol then pseudo_map.key?(key) || breakpoint?(key)
+        else false
+        end
+      end
+
+      def pseudo_element?(key)
+        resolved = key.is_a?(String) ? key : pseudo_map[key]
+        resolved.is_a?(String) && resolved.start_with?("::")
+      end
+
+      def self.validate_pseudo_map!(map)
+        raise ArgumentError, "pseudo_map must be a Hash, got #{map.class}" unless map.is_a?(Hash)
+
+        map.each do |key, value|
+          raise ArgumentError, "pseudo_map key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
+          unless value.is_a?(String) && value.start_with?(":", "@")
+            raise ArgumentError, "pseudo_map #{key.inspect} must be a String starting with ':' or '@', got #{value.inspect}"
+          end
+        end
+      end
+
+      def self.validate_breakpoints!(map, pseudo_map:)
+        raise ArgumentError, "breakpoints must be a Hash, got #{map.class}" unless map.is_a?(Hash)
+
+        map.each do |key, query|
+          raise ArgumentError, "breakpoint name must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
+          raise ArgumentError, "breakpoint #{key.inspect} must be a String, got #{query.inspect}" unless query.is_a?(String)
+          if pseudo_map.key?(key)
+            raise ArgumentError, "breakpoint #{key.inspect} collides with the pseudo-class or media shortcut of the same name"
+          end
+        end
+      end
+
+      def resolve(key)
+        case key
+        when Symbol
+          if (breakpoint = breakpoints[key])
+            return breakpoint.start_with?("@") ? breakpoint : "@media #{breakpoint}"
+          end
+
+          pseudo_map[key] ||
+            raise(ArgumentError, "Unknown style condition #{key.inspect}. " \
+                                 "Use a known pseudo-class symbol, a configured breakpoint, " \
+                                 "or a string such as \":nth-child(2)\" or \"@media (...)\".")
+        when String
+          unless key.start_with?(":", "@")
+            raise ArgumentError, "Style condition strings must start with ':' or '@', got #{key.inspect}"
+          end
+          key
+        else
+          raise ArgumentError, "Unsupported style condition #{key.inspect}"
+        end
+      end
+    end
+  end
+end