windsock 0.1.0

data/lib/windsock/parser.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Windsock
+  # Extracts theme variables from Tailwind v4 CSS.
+  #
+  # Walks the stylesheet looking for top-level `@theme { ... }` blocks and
+  # `@import` statements. Everything else (`@layer`, `@utility`, plain rules)
+  # is skipped. `@import "tailwindcss"` pulls in the bundled default theme.
+  #
+  # Precedence follows Tailwind: values from `@theme default` blocks never
+  # override values set in a regular `@theme` block, regardless of order.
+  # `--color-*: initial` clears a namespace; `--*: initial` clears everything.
+  class Parser
+    TAILWIND_IMPORTS = %w[tailwindcss tailwindcss/theme tailwindcss/theme.css].freeze
+
+    attr_reader :vars, :files
+
+    def self.parse(css, base_dir: nil)
+      new.parse(css, base_dir: base_dir)
+    end
+
+    def self.parse_file(path)
+      new.parse_file(path)
+    end
+
+    def initialize
+      @vars = {}
+      @owned = {} # keys set by a non-default @theme block
+      @files = []
+    end
+
+    def parse_file(path)
+      path = File.expand_path(path)
+      return self if files.include?(path)
+
+      files << path
+      parse(File.read(path), base_dir: File.dirname(path))
+    end
+
+    def parse(css, base_dir: nil)
+      Scanner.new(strip_comments(css)).each_rule do |name, prelude, body|
+        case name
+        when "import" then import(prelude, base_dir)
+        when "theme" then theme_block(prelude, body)
+        end
+      end
+      self
+    end
+
+    private
+
+    def strip_comments(css)
+      css.gsub(%r{/\*.*?\*/}m, "")
+    end
+
+    def import(prelude, base_dir)
+      spec = prelude[/\A\s*(?:url\()?\s*["']([^"']+)["']/, 1]
+      return unless spec
+
+      if TAILWIND_IMPORTS.include?(spec)
+        parse_file(Windsock.default_theme_path)
+      elsif spec.start_with?("./", "../", "/")
+        parse_file(resolve_import(spec, base_dir))
+      end
+      # Bare specifiers ("tailwindcss/utilities", "tw-animate-css", ...) are ignored.
+    end
+
+    def resolve_import(spec, base_dir)
+      base = spec.start_with?("/") ? spec : File.expand_path(spec, base_dir || Dir.pwd)
+      candidates = [base, "#{base}.css", File.join(base, "index.css")]
+      candidates.find { |path| File.file?(path) } ||
+        raise(ImportError, "cannot resolve @import #{spec.inspect} from #{base_dir || Dir.pwd}")
+    end
+
+    def theme_block(prelude, body)
+      default = prelude.split.include?("default")
+      Scanner.new(body).each_declaration do |name, value|
+        next unless name.start_with?("--")
+
+        key = name[2..]
+        value = value.gsub(/\s*\n\s*/, " ")
+        if value == "initial"
+          reset(key)
+        else
+          assign(key, value, default)
+        end
+      end
+    end
+
+    def assign(key, value, default)
+      return if default && @owned[key]
+
+      @vars[key] = value
+      @owned[key] = true unless default
+    end
+
+    def reset(key)
+      if key == "*"
+        @vars.clear
+        @owned.clear
+      elsif key.end_with?("-*")
+        prefix = key[0..-2]
+        @vars.delete_if { |k, _| k.start_with?(prefix) }
+        @owned.delete_if { |k, _| k.start_with?(prefix) }
+      else
+        @vars.delete(key)
+        @owned.delete(key)
+      end
+    end
+
+    # Minimal CSS tokenizer: finds at-rules and declarations at one nesting
+    # level, honouring strings, parentheses and braces.
+    class Scanner
+      def initialize(css)
+        @css = css
+        @pos = 0
+      end
+
+      # Yields [name, prelude, body] for each at-rule. Body is nil for
+      # statement at-rules (`@import ...;`). Other rules are skipped.
+      def each_rule
+        until eof?
+          skip_whitespace
+          break if eof?
+
+          if peek == "@"
+            yield(*read_at_rule)
+          else
+            skip_rule
+          end
+        end
+      end
+
+      # Yields [name, value] for each declaration. Nested blocks (e.g.
+      # `@keyframes` inside `@theme`) are skipped.
+      def each_declaration
+        until eof?
+          skip_whitespace
+          break if eof?
+
+          if peek == "@"
+            read_at_rule
+          elsif peek == ";"
+            advance
+          else
+            text = read_until(";", "{", "}")
+            if peek == "{"
+              skip_block
+            else
+              advance if peek == ";"
+              name, value = text.split(":", 2)
+              yield(name.strip, value.strip) if value
+            end
+          end
+        end
+      end
+
+      private
+
+      def eof? = @pos >= @css.length
+      def peek = @css[@pos]
+      def advance = (@pos += 1)
+
+      def skip_whitespace
+        @pos += 1 while !eof? && peek.match?(/\s/)
+      end
+
+      def read_at_rule
+        advance # "@"
+        name = @css[@pos..][/\A[\w-]+/] || ""
+        @pos += name.length
+        prelude = read_until(";", "{", "}").strip
+
+        case peek
+        when "{"
+          [name, prelude, read_block]
+        else
+          advance if peek == ";"
+          [name, prelude, nil]
+        end
+      end
+
+      def skip_rule
+        read_until(";", "{")
+        peek == "{" ? skip_block : advance
+      end
+
+      def skip_block
+        read_block
+      end
+
+      # Assumes peek == "{". Returns the inner text and moves past "}".
+      def read_block
+        advance
+        start = @pos
+        depth = 1
+        until eof?
+          char = peek
+          if %w[" '].include?(char)
+            skip_string
+            next
+          end
+          depth += 1 if char == "{"
+          depth -= 1 if char == "}"
+          advance
+          return @css[start...(@pos - 1)] if depth.zero?
+        end
+        @css[start..]
+      end
+
+      # Reads until one of the stop chars at paren depth zero, outside strings.
+      def read_until(*stops)
+        start = @pos
+        depth = 0
+        until eof?
+          char = peek
+          if %w[" '].include?(char)
+            skip_string
+            next
+          end
+          depth += 1 if char == "("
+          depth -= 1 if char == ")" && depth.positive?
+          break if depth.zero? && stops.include?(char)
+
+          advance
+        end
+        @css[start...@pos]
+      end
+
+      def skip_string
+        quote = peek
+        advance
+        until eof?
+          char = peek
+          advance
+          if char == "\\"
+            advance
+          elsif char == quote
+            break
+          end
+        end
+      end
+    end
+  end
+end

data/lib/windsock/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Windsock
+  class Railtie < ::Rails::Railtie
+    config.windsock = ActiveSupport::OrderedOptions.new
+
+    initializer "windsock.path" do |app|
+      Windsock.path ||= app.config.windsock.path || app.root.join("app/assets/tailwind/application.css")
+    end
+
+    initializer "windsock.helper" do
+      ActiveSupport.on_load(:action_view) { include Windsock::Helper }
+    end
+
+    # Re-parse when any CSS under the stylesheet's directory changes.
+    initializer "windsock.reloader" do |app|
+      config = app.config
+      reloading = config.respond_to?(:reloading_enabled?) ? config.reloading_enabled? : !config.cache_classes
+      next unless reloading
+
+      dir = File.dirname(Windsock.path.to_s)
+      next unless File.directory?(dir)
+
+      watcher = app.config.file_watcher.new([], { dir => ["css"] }) { Windsock.reset! }
+      app.reloaders << watcher
+      app.reloader.to_run { watcher.execute_if_updated }
+    end
+  end
+end

data/lib/windsock/scale.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "pp"
+
+module Windsock
+  # One color scale from the theme: scale(:brand) => 50..950 steps.
+  #
+  # Behaves like a Hash of step => Color (Enumerable over [step, color]
+  # pairs) and adds WCAG contrast lookups so you can pick a usable step
+  # without leaving the console.
+  #
+  #   scale = Windsock.scale(:brand)
+  #   scale[500].to_hex                       # "#2b7fff"
+  #   scale.contrast(:white)                  # { 50 => 1.05, ..., 950 => 17.3 }
+  #   scale.accessible(on: :white).steps      # steps that pass AA for text
+  #   scale.text_colors[500].to_hex           # "#ffffff" — text to put on brand-500
+  #
+  # "white" and "black" mean the theme's --color-white / --color-black when
+  # the scale came from a theme (an app may soften white to #f5f5f5), and
+  # pure #fff / #000 otherwise. Any other name is looked up in the theme
+  # first (scale.contrast(:surface)), then parsed as CSS.
+  class Scale
+    include Enumerable
+
+    attr_reader :name
+
+    def initialize(name, steps, theme: nil)
+      @name = name.to_s
+      @theme = theme
+      @steps = steps.to_h { |step, color| [normalize(step), Color.parse!(color)] }.freeze
+    end
+
+    def white
+      @theme&.white || Color::WHITE
+    end
+
+    def black
+      @theme&.black || Color::BLACK
+    end
+
+    # scale[500], scale["500"], scale[:muted] all work.
+    def [](step)
+      @steps[normalize(step)]
+    end
+
+    def fetch(step)
+      self[step] || raise(NotFound, "scale #{name.inspect} has no step #{step.inspect}")
+    end
+
+    def step?(step)
+      @steps.key?(normalize(step))
+    end
+    alias key? step?
+
+    def steps
+      @steps.keys
+    end
+    alias keys steps
+
+    def colors
+      @steps.values
+    end
+    alias values colors
+
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @steps.each(&)
+    end
+
+    def size
+      @steps.size
+    end
+    alias length size
+
+    def empty?
+      @steps.empty?
+    end
+
+    def to_h
+      @steps.dup
+    end
+
+    # WCAG contrast ratio of every step against +on+ (a Color, a theme color
+    # name, or any CSS color): { 50 => 1.05, 100 => 1.12, ... }.
+    def contrast(on = :white)
+      other = resolve(on)
+      @steps.transform_values { |color| color.contrast(other).round(2) }
+    end
+
+    # The steps whose contrast against +on+ meets a WCAG level, as a new
+    # Scale. Levels: :aa (4.5), :aa_large (3), :aaa (7), :aaa_large (4.5).
+    #
+    #   scale.accessible(on: :white)               # text colors usable on white
+    #   scale.accessible(on: :black, level: :aaa)
+    def accessible(on: :white, level: :aa)
+      other = resolve(on)
+      Scale.new(name, @steps.select { |_, color| color.accessible?(other, level: level) }, theme: @theme)
+    end
+
+    # The theme's black or white, per step, for text placed on that step:
+    # { 50 => #000000, ..., 900 => #ffffff }.
+    def text_colors
+      @steps.transform_values { |color| color.text_color(white: white, black: black) }
+    end
+
+    def ==(other)
+      other.is_a?(Scale) && name == other.name && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      [name, @steps].hash
+    end
+
+    def to_s
+      "#{name}: " + @steps.map { |step, color| "#{step}=#{color.to_hex}" }.join(" ")
+    end
+
+    # A table, one row per step: contrast against white and black, and the
+    # text color to use on the step. Ratios that meet +level+ (default AA,
+    # 4.5:1) print green, the rest red, when +color+ is on. +color+ defaults
+    # to whether stdout is a terminal, so logs and tests stay plain.
+    #
+    #   scale.table                      # what the console shows
+    #   scale.table(level: :aaa)
+    #   puts scale.table(color: false)
+    def table(level: DEFAULT_LEVEL, color: $stdout.tty?)
+      return "#<Windsock::Scale #{name} (empty)>" if empty?
+
+      minimum = Color::WCAG.fetch(level) { raise ArgumentError, "level must be one of #{Color::WCAG.keys.join(", ")}" }
+      width = steps.map { |s| s.to_s.length }.max
+      rows = @steps.map do |step, c|
+        format("  %#{width}s  %-9s  %s  %s  %s", step, c.to_hex,
+               ratio_cell(c.contrast(white), minimum, color),
+               ratio_cell(c.contrast(black), minimum, color),
+               c.text_color(white: white, black: black) == white ? "white" : "black")
+      end
+      header = format("  %#{width}s  %-9s  %6s  %6s  %s", "step", "hex", "white", "black", "text")
+      title = "#<Windsock::Scale #{name} (#{size} steps; contrast vs white #{white.to_hex} / black #{black.to_hex}; " \
+              "#{level.to_s.upcase.tr("_", " ")} needs #{minimum}:1; text = what to write on it)"
+      [title, header, *rows, ">"].join("\n")
+    end
+
+    def inspect
+      table
+    end
+
+    # IRB's pretty printer wraps anything that inspects as #<...> in green and
+    # re-lexes the rest as Ruby, so the first red cell ended its green and
+    # the rows after it came out half-coloured. Hand it the finished table
+    # through the base PrettyPrint#text so nothing is re-coloured.
+    def pretty_print(q)
+      PrettyPrint.instance_method(:text).bind_call(q, table)
+    end
+
+    DEFAULT_LEVEL = :aa
+    GREEN = "\e[32m"
+    RED = "\e[31m"
+    RESET = "\e[0m"
+
+    private
+
+    # :white / :black => the theme's; another theme color name => that;
+    # a Color => itself; anything else => parsed as CSS.
+    def resolve(on)
+      return on if on.is_a?(Color)
+
+      key = on.to_s
+      return white if key == "white"
+      return black if key == "black"
+
+      themed = @theme && @theme[:color, key]
+      Color.parse!(themed || key)
+    end
+
+    def ratio_cell(ratio, minimum, color)
+      cell = format("%6.2f", ratio)
+      return cell unless color
+
+      "#{ratio >= minimum ? GREEN : RED}#{cell}#{RESET}"
+    end
+
+    def normalize(step)
+      text = step.to_s
+      text.match?(/\A\d+\z/) ? text.to_i : text
+    end
+  end
+end

data/lib/windsock/tailwind/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.